Webhooks

If you want to track the different events of your customer lifecycle, being able to make productive decisions for your business, we have great news for you: you don’t need to quit Rebill to set-up your own webhooks and receive notifications in other systems.

Events

You can configure webhooks based on the following events:

New payment. Every time a payment is made.
New subscription. Every time a new customer signs up to a subscription product.
24 hours forewarning payment. 24 hours before an automatic debit is made (on subscriptions or cyclic payments).
Payment status change. When it goes, for example, from pending to approved / rejected.
Subscription status change. When it is canceled or a subscriber changes his plan.

Use case

Next question is: when do we use webhooks? Let’s see a real case…

Example:

Suppose your business sells fruit, so you want to offer your customers a subscription plan to receive a personalized fruit crate every month.

To send the orders the exact day the payment is made, you can configure the webhook "24 hours forewarning payment" to be notified when you should prepare the crates for your customers.

In this way, you can prepare your orders in advance, to send them at the right time and give your customers the best experience.

How to set-up your webhooks?

You can configure your webhooks in 2 simple steps, in a simple and intuitive way:

Go to the “Webhooks” section (left menu) and, to create a webhook, click on this option in the upper right corner.

Choose the event you want to be notified about, fill in the destination URL for that webhook, and click "Ok".

Examples

Examples of the data structures that respond to each event detailed below.

New payment event / succeeded payment

{
   "payment":{
      "id":"e23d4a48-7aa6-45a0-94f4-cd254062f0dc",
      "status":"SUCCEEDED",
      "amount":"1.23",
      "currency":"EUR",
      "createdAt":"2022-10-27T22:09:48.845Z",
      "paymentMethod":"CARD",
      "customer":{
         "email":"[email protected]"
      },
      "card":{
         "id":"b704b0d6-3714-46d0-8c5c-1a63ee5941c1"
      },
      "organization":{
         "id":"41c4be3f-6366-4984-b9e1-21d5050131a8"
      },
      "gateway":{
         "country":"UK",
         "type":"stripe"
      },
   },
   "webhook":{
      "id":"987d33b1-2f0b-4efc-bc02-bf9d3a04a850",
      "event":"new-payment",
      "url":"https://your.domain/new-payment",
      "logId":"596168f-ed10-4619-9eb2-a48b8a6744e2"
   }
}

New payment event / failed payment

{
   "payment":{
      "id":"f61def1c-d33b-4530-925a-89248529148a",
      "status":"FAILED",
      "amount":"1.23",
      "currency":"EUR",
      "createdAt":"2022-10-27T22:10:07.482Z",
      "paymentMethod":"CARD",
      "customer":{
         "email":"[email protected]"
      },
      "card":{
         "id":"b1ccaac6-e216-4f26-acb4-41627037b167"
      },
      "organization":{
         "id":"11f421ed-7421-4643-b769-fdb181c2d5c8"
      },
      "gateway":{
         "country":"UK",
         "type":"stripe"
      },
   },
   "webhook":{
      "id":"987233b1-2f0b-4efc-bc02-bf9d3a04a850",
      "event":"new-payment",
      "url":"https://your.domain/new-payment",
      "logId":"59ce68f-ed10-4619-9eb2-a48b8a6744e2"
   }
}

New subscription event

{
   "subscription":{
      "card":{
         "id":"768a36df-4d8f-45e4-a585-83e506c76da5",
         "last_four_digits":"4242"
      },
      "customer":{
         "email":"[email protected]"
      },
      "gateway":{
         "country":"UK",
         "type":"stripe"
      },
      "organization":{
         "id":"28fae0e5-4a5f-4086-bb47-7aa41ed18367"
      },
      "payment":{
         "id":"346f7281-de01-48ba-bd8c-4648e4139d7c",
         "gatewayPaymentId":"ch_5NqoGmLdmyGpZQ0W2OFgzWQz"
      },
      "subscription":{
         "id":"ec81b44f-d5bd-4368-b48c-eeeab106c454",
         "createdAt":"2022-10-27T22:09:48.884Z",
         "price":{
            "id":"2e05f975-2cc6-4e17-babb-c556ebd8e4b9",
            "currency":"EUR",
            "debitDay":null,
            "debitType":null,
            "decimalPlaces":2,
            "description":"this the price's description",
            "enabled":true,
            "frequency":{
               "quantity":1,
               "type":"months"
            },
            "item":{
               "id":"5fdb78c1-0b50-4e74-bf0b-00d0f746fabc",
               "createdAt":"2022-10-27T21:58:49.551Z",
               "description":"The product's name",
               "itemFamilyId":null,
               "metadata":[
                  
               ],
               "name":"Example product"
            },
            "priceSetting":{
               "id":"57ccd341-0261-4599-9baf-072dfbe6c1e4",
               "billingAddressRequired":true,
               "documentRequired":true,
               "phoneRequired":true,
               "redirectUrl":"rebill.to",
               "showImage":true
            },
            "repetitions":null,
            "type":"fixed",
            "value":"123"
         },
         "quantity":1,
         "title":"Example product"
      }
   },
   "webhook":{
      "id":"617d33b1-2f0b-4efc-bc02-bf9d3a04a850",
      "event":"new-subscription",
      "url":"https://your.domain/new-subscription",
      "logId":"591968f-ed10-4619-9eb2-a48b8a6744e2"
   }
}

Payment change status event

{
  "payment": {
   "id": "024160d0-7ba4-48c0-828e-b2c6fab86e53",
   "createdAt": "2022-09-06T14:38:00.082Z",
   "newStatus": "REFUNDED",
   "orderId": "637285ca-85f5-476e-bade-40b6ec61da2c",
   "previousStatus": "SUCCEEDED"
  },
   "webhook":{
      "id":"bf8d33b1-2f0b-4efc-bc02-bf9d3a04a850",
      "event":"payment-change-status",
      "url":"https://your.domain/payment-change-status",
      "logId":"eeb168f-ed10-4619-9eb2-a48b8a6744e2"
   }
 }

Subscription status change event

{
   "billingScheduleId":"ac0a2bcf-3240-446f-abcf-501ee3742b7e",
   "newStatus":"ACTIVE",
   "oldStatus":"PAUSED",
   "webhook":{
      "id":"ae7d33b1-2f0b-4efc-bc02-bf9d3a04a850",
      "event":"subscription-change-status",
      "url":"https://your.domain/subscription-change-status",
      "logId":"5bb168f-ed10-4619-9eb2-a48b8a6744e2"
   }
}

Subscription charge in 24 hours event

{
  "id": "e41862c6-636d-460e-9bd9-eb2682dada44",
  "buyer": {
   "card": {
    "id": "0bc0d935-920c-4de5-8a58-80aa31552ff0",
    "cardholder": "JOHN DOE",
    "cardNumber": "424242bx_0a30839da0c7451387d0793e9ed362c4_bx4242",
    "expirationMonth": "03",
    "expirationYear": "2039",
    "personalIdNumber": "11312412",
    "personalIdType": "DNI",
    "securityCode": null
   },
   "customer": {
    "profile": {
     "id": "d905b703-846c-480a-bc1d-ea3bfcd4ba17",
     "birthday": null,
     "cellPhone": null,
     "createdAt": "2022-09-19T18:40:41.644Z",
     "firstName": "John",
     "lastName": "Doe",
     "personalIdNumber": "11312412",
     "personalIdType": "DNI",
     "taxIdNumber": null,
     "taxIdType": null
    },
    "user": {
     "id": "6750e15d-4730-4467-85f1-dface272eff6",
     "cards": [
     ],
     "createdAt": "2022-09-19T18:40:41.632Z",
     "email": "[email protected]",
     "enabled": true,
     "password": "dummy.password",
     "profile": {
      "id": "fc8d778f-8c28-45cb-9756-654106d9030e",
      "birthday": null,
      "cellPhone": null,
      "createdAt": "2022-09-19T18:40:41.644Z",
      "firstName": "John",
      "lastName": "Doe",
      "personalIdNumber": "11312412",
      "personalIdType": "DNI",
      "taxIdNumber": null,
      "taxIdType": null
     },
     "roles": [
      {
       "id": "0588e5f5-0fa9-47d0-856e-17b6a029cc7c",
       "createdAt": "2022-05-05T13:23:12.904Z",
       "description": "Customer of organization",
       "organization": {
        "id": "a2b82057-f15d-4d4a-88ad-b66197207f9f",
        "alias": "example",
        "compliance": false,
        "customCheckoutUrl": null,
        "logoUrl": "https://dashboard.rebill.to/images/e00ac2e0c4b31eb638b9a7706dde.png",
        "name": "example SAS",
        "ownerId": "5eb51cb4-f1ab-4e65-a325-e60f99c61d66"
       },
       "permissions": [
       ],
       "_name": "customer"
      }
     ]
    }
   }
  },
  "createdAt": "2022-09-19T18:40:43.148Z",
  "currency": "ARS",
  "debitDay": null,
  "debitType": null,
  "decimalPlaces": 0,
  "description": null,
  "externalReference": "",
  "frequency": {
   "quantity": 1,
   "type": "months"
  },
  "item": {
   "id": "3f96299d-ad98-4a56-b26f-61871a348ffd",
   "createdAt": "2022-05-05T13:46:57.909Z",
   "description": "An item description",
   "itemFamilyId": "36d5f3a8-d0e6-489e-b4e0-d5fcd02ec8f7",
   "metadata": null,
   "name": "Item dummy"
  },
  "metadataObject": null,
  "paymentsIds": [
  ],
  "price": {
   "id": "0b6cdcb0-b5a4-4bce-bcab-380e4912f2af",
   "country": "AR",
   "description": "a gateway sandbox",
   "organization": {
    "id": "3179350a-811f-4221-994b-7a815952c5f9",
    "alias": "example",
    "customCheckoutUrl": null,
    "name": "example SAS",
    "ownerId": "e939411b-b193-423c-a72e-497346142a4f"
   },
   "type": "dlocal"
  },
  "quantity": 1,
  "repetitions": 2,
  "type": "fixed",
  "updateSubscribers": [
  ],
  "user": {
   "email": "[email protected]",
  },
  "value": "412",
  "_balance": {
   "decimalPlaces": 0,
   "value": 0
  },
  "_lastChargeDate": "2022-09-19T18:40:43.000Z",
  "_nextChargeDate": "2022-10-19T18:40:43.000Z",
  "_recoveryToken": null,
  "_remainingIterations": 1,
  "_status": {
   "id": "ACTIVE"
  },
   "webhook":{
      "id":"66cd33b1-2f0b-4efc-bc02-bf9d3a04a850",
      "event":"subscription-charge-in-24-hours",
      "url":"https://your.domain/subscription-charge-in-24-hours",
      "logId":"5eb168f-ed10-4619-9eb2-a48b8a6744e2"
   }
 }