Webhooks
Receive notifications in other systems for different customer lifecycle events.
Webhooks let you subscribe to specific events in Rebill. When a subscribed event occurs, Rebill sends a notification that includes a JSON payload with the event information. Also, you can create more than one webhook for each event.
Events
You can configure webhooks based on the following events:
- New Payment
- New Subscription
- Payment Status Change
- Subscription Status Change
- 24 hours forewarning payment
New Payment
This event is triggered when a new payment is made.
These are the possible types for a new payment:
| Type | Description |
|---|---|
FirstPayment | First time payment. |
SubscriptionPayment | Payment for a recurring subscription cycle. |
PlanUpdate | Change in subscription plan details. |
PaymentRetry | Attempt to process a payment again after a failure. |
SingleProcessPayment | One-time payment for a non-recurring service or product. |
Here's an example of a New Payment webhook response:
[
{
"event": "SubscriptionPayment",
"payment": {
"id": "xxxxxxx-b5b0-44a3-xx-xxxxxxxxx",
"card": {
"id": "xxxxxxxxx-7920-xxx-ace9-xx"
},
"amount": "75990",
"status": "SUCCEEDED",
"gateway": {
"type": "rebill_gateway",
"country": "CL"
},
"currency": "CLP",
"customer": {
"email": "test@gmail.com"
},
"createdAt": "2024-04-03T13:53:04.279Z",
"organization": {
"id": "xxxxx-3c16-4149-xxxx-a37821aa7a25"
},
"paymentMethod": "CARD"
},
"priceId": "xxxx-3deb-xx-a760-a859810a1d79",
"subscriptionId": "85dac77c-e740-4b2f-b275-644ece354aaa",
"webhook": {
"id": "xxxxxxx-cf15-xxx-xxxx-8b93e11fb219",
"event": "new-payment",
"url": "https://example.com",
"logId": "xxxxxx-a059-xxx-bc44-71c9ea680cb8"
}
}
]
New subscription
Every time a new customer signs up to a subscription product.
Here's an example of a New Subscription webhook response:
[
{
"subscription": {
"id": "xxxxxx-c477-43f6-xxxx-9634e9650ab8",
"title": "Basic Subscription",
"price": {
"frequency": {
"type": "months",
"quantity": 1
},
"repetitions": null,
"currency": "COP",
"value": "10",
"decimalPlaces": 0,
"item": {
"name": "Basic Subscription",
"description": "Monthly subscription basic plan",
"metadata": {},
"type": "plan",
"archive": false,
"assets": null,
"id": "xxxxx-ee46-xx-a939-5bf5f5f648ab",
"createdAt": "2024-03-13T14:47:23.491Z",
"itemFamilyId": null
},
"description": null,
"debitDay": null,
"debitType": null,
"priceSetting": {
"documentRequired": true,
"phoneRequired": true,
"billingAddressRequired": true,
"showImage": true,
"redirectUrl": null,
"paymentMethods": [
{
"type": "CASH",
"metadata": {
"name": "REBILL_EFECTY",
"formalName": "Efecty",
"type": "REDIRECT_LINK",
"countries": [
"CO"
],
"gatewayPaymentMethodId": 38
}
},
{
"type": "TRANSFER",
"metadata": {
"name": "REBILL_NEQUI_QR",
"formalName": "Nequi QR",
"type": "QR",
"countries": [
"CO"
],
"gatewayPaymentMethodId": 67
}
},
{
"type": "TRANSFER",
"metadata": {
"name": "REBILL_NEQUI_PUSH",
"formalName": "Nequi Push",
"type": "QR",
"countries": [
"CO"
],
"gatewayPaymentMethodId": 68
}
},
{
"type": "CARD",
"metadata": {
"name": "CARD",
"formalName": "Card",
"countries": [
"AR",
"CL",
"CO",
"BR",
"MX",
"PE"
]
}
}
],
"expirationDate": null,
"allowDiscountCodes": true,
"id": "xx-0e5b-xx-xx-d98214f702b6"
},
"archive": false,
"type": "fixed",
"id": "xx-3cdf-4ed7-a3f6-c5cffbce465f",
"createdAt": "2024-03-13T14:47:23.513Z"
},
"quantity": 1,
"createdAt": "2024-04-03T18:57:11.997Z"
},
"payment": {
"id": "xxxx-4f98-4c2d-b9ff-8784aeb30a3e",
"gatewayPaymentId": 1283358
},
"customer": {
"email": "franco@rebill.com"
},
"organization": {
"id": "xxxxx-ff7e-xx-ac1b-586e133dcfbe"
},
"gateway": {
"type": "rebill_gateway",
"country": "I"
},
"card": {
"id": "xxxxxx-4604-4071-xxxxx-f7dddefecbf5",
"last_four_digits": "5534"
},
"webhook": {
"id": "xx-9e2c-xx-xx-e3988db316c4",
"event": "new-subscription",
"url": "https://example.com",
"logId": "xxx-c1c3-49d8-9472-7244abc31e06"
}
}
]
Payment status change
When a payment changes its status. For example, a pending payment that becomes approved.
[
{
"payment": {
"id": "xxxx-4f98-4c2d-xx-8784aeb30a3e",
"previousStatus": "SUCCEEDED",
"newStatus": "REFUNDED",
"orderId": "xxxxxxxx-b28a-xxxxx-xx-db1b190c39fd",
"createdAt": "2024-04-03T18:57:11.629Z"
},
"webhook": {
"id": "xxxxx-cd4d-xx-xx-a735b49b64b4",
"event": "payment-change-status",
"url": "https://example.com",
"logId": "xxxxxxx-04f4-xx-xx-f9dfcbcdd845"
}
}
]
Subscription status change
When a subscription changes its status. For example, if a subscriptionis paused, or if it enters retrying state after a failed payment.
[
{
"newStatus": "PAUSED",
"oldStatus": "ACTIVE",
"billingScheduleId": "xxxx-5356-xx-a10c-xxxxxx",
"webhook": {
"id": "xx-24c6-xxxxxx-b14b-xxxxx",
"event": "subscription-change-status",
"url": "https://example.com",
"logId": "xxxxxx-xx-4e41-x-8b5d15376c6c"
}
}
]
24 hours forewarning payment
24 hours before an automatic debit is made (on subscriptions or cyclic payments).
[
{
"id": "xxxxxxx-c477-xxx-xxxxxx-9634e9650ab8",
"buyer": {
"card": {
"expirationYear": "2026",
"personalIdNumber": "1234567890",
"securityCode": "bx_xxxxxxxxxxxxxxa2467b02476a21d6_bx",
"personalIdType": "CC",
"expirationMonth": "06",
"id": "xxae9da-xxxx-4071-xx-f7dddefecbf5",
"cardholder": "FRANCO REBILL",
"cardNumber": "xxxxxxxxxxxxxxxxxxxxxx"
},
"customer": {
"user": {
"createdAt": {},
"password": "$xxx$xxxxx$xxxxxxxxxxxxxxxx.xxxxxxxxxxx",
"cards": [],
"profile": {
"birthday": null,
"firstName": "Franco",
"lastName": "Rebill",
"createdAt": {},
"address": {
"number": "",
"country": "CO",
"zipCode": "",
"apt": "A",
"city": "Amazonas",
"street": "Calle 123, CDF1",
"description": null,
"state": "Amazonas",
"id": "xxxxxxx-411d-xx-xx-7bf26fcd6657",
"floor": "1"
},
"taxIdNumber": "",
"personalIdNumber": "1234567890",
"personalIdType": "CC",
"taxIdType": "",
"avatar": null,
"id": "991d7f6a-0cdf-4f22-9fc9-fbff0c1ffa96",
"cellPhone": "57-11111111"
},
"roles": [
{
"description": "Customer of organization",
"createdAt": {},
"id": "xxxxx-725d-xx-xx-bdcc98f65450",
"_name": "customer",
"permissions": [
"GET_ORGANIZATION"
],
"organization": {
"metadata": null,
"customCheckoutCss": null,
"address": {
"number": "-",
"country": "Argentina",
"zipCode": "1419",
"apt": "1",
"city": "Buenos Aires Capital",
"street": "Mosconi 123",
"description": null,
"state": "Buenos Aires Capital",
"id": "522a6f28-0ed2-4eb9-b97e-f7850d4bce98",
"floor": null
},
"_legalInformation": {
"legalName": "Cursos Online",
"country": "Argentina",
"zipCode": "1419",
"state": "Buenos Aires Capital",
"businessType": "COMPANY",
"businessAddress": "Mosconi 123",
"apartment": "1",
"annualRevenue": "250000_1000000"
},
"statementDescriptor": "Cursos Online",
"customCheckoutJs": null,
"ownerId": "d1d865e1-11ca-4f48-a68f-aadf9f785681",
"logoUrl": "https://example.com",
"lastStepCompleted": "member-invited",
"checkoutUrl": "https://pay.rebill.com",
"notificationSettings": {
"eventsNotifiedByMessage": [],
"attachReceiptFile": true,
"eventsNotifiedByEmail": [
"cancelled-subscription",
"initial-charge-accredited",
"initial-charge-in-process",
"initial-charge-rejected",
"new-order",
"new-subscription",
"paused-subscription",
"payment-refund",
"reactive-subscription",
"recurring-charge-rejected",
"recurring-charge-accredited",
"recurring-charge-in-process",
"retry-charge-rejected",
"retry-charge-accredited",
"retry-charge-in-process",
"profile-created",
"member-invited",
"change-card-request",
"portal-customer-welcome",
"export-payments-report-to-csv",
"renewal-soon-expiring-card-request",
"defaulted-subscription",
"apm-subscription-renewal",
"export-subscriptions-report-to-csv",
"customer-otp-created"
],
"organization": {
"parent": null,
"metadata": null,
"address": null,
"statementDescriptor": null,
"logoUrl": null,
"checkoutUrl": null,
"notificationSettings": {
"eventsNotifiedByEmail": [
"cancelled-subscription",
"initial-charge-accredited",
"initial-charge-in-process",
"initial-charge-rejected",
"new-order",
"new-subscription",
"paused-subscription",
"payment-refund",
"reactive-subscription",
"recurring-charge-rejected",
"member-invited",
"change-card-request",
"export-payments-report-to-csv"
],
"organization": {},
"eventsNotifiedByMessage": []
},
"customerPortalUrl": null,
"compliance": false,
"name": "null",
"alias": "null",
"retriesSettings": [
{
"propertyToLookFor": "nextChargeDate",
"order": 1,
"frequency": {
"type": "days",
"quantity": 1
}
},
{
"propertyToLookFor": "lastRetryingDate",
"order": 2,
"frequency": {
"type": "days",
"quantity": 1
}
},
{
"propertyToLookFor": "lastRetryingDate",
"order": 3,
"frequency": {
"type": "days",
"quantity": 1
}
}
],
"id": "fake-id",
"currencies": null
},
"mailerUser": null,
"customerSupportResponseTime": null,
"mailerProvider": null,
"id": "xxxx-xx-47a6-xxxxxx-xx",
"mailerPassword": null,
"mailerHost": null,
"customerSupportEmail": null,
"mailerFrom": null
},
"refundTermsAndConditionsLink": null,
"compliance": false,
"name": "Cursos Online",
"alias": "cursosonline",
"id": "xxxxx-xx-45c7-xxxx-xx",
"currencies": null
}
}
],
"id": "xx-b011-xxxxxx-9213-x",
"email": "franco@rebill.com",
"enabled": true
},
"profile": {
"birthday": null,
"firstName": "Franco",
"lastName": "Rebill",
"createdAt": {},
"address": {
"number": "",
"country": "CO",
"zipCode": "",
"apt": "A",
"city": "Amazonas",
"street": "Calle 123, CDF1",
"description": null,
"state": "Amazonas",
"id": "xxxx-411d-4a23-xx-x",
"floor": "1"
},
"taxIdNumber": "",
"personalIdNumber": "1234567890",
"personalIdType": "CC",
"taxIdType": "",
"avatar": null,
"id": "xxxxxxx-x-xx-9fc9-xx",
"cellPhone": "57-11111111"
}
}
},
"createdAt": "2024-04-03T18:57:11.997Z",
"currency": "COP",
"debitDay": null,
"debitType": null,
"decimalPlaces": 0,
"description": "Basic Subscription",
"externalReference": "",
"frequency": {
"type": "months",
"quantity": 1
},
"item": {
"name": "Basic Subscription",
"description": "Monthly subscription basic plan",
"metadata": {},
"type": "plan",
"archive": false,
"assets": null,
"id": "xx-xx-xx-a939-xxxxxxx",
"createdAt": "2024-03-13T14:47:23.491Z",
"itemFamilyId": null
},
"metadataObject": {},
"paymentsIds": [],
"price": {
"id": "xxx-3cdf-x-xxxx-xxxxxxxxx",
"country": "I",
"description": null,
"organization": {
"id": "xxxxx-ff7e-xxx-ac1b-xxxx",
"alias": "cursosonline",
"checkoutUrl": "https://pay.rebill.com",
"name": "Cursos Online",
"ownerId": "d1d865e1-11ca-4f48-a68f-aadf9f785681"
},
"type": "rebill_gateway"
},
"quantity": 1,
"repetitions": null,
"type": "fixed",
"user": {
"email": "franco@rebill.com"
},
"value": "10",
"_balance": {
"value": 0,
"decimalPlaces": 0
},
"_lastChargeDate": "2024-04-03T18:57:12.000Z",
"_nextChargeDate": "2024-04-04T21:57:12.000Z",
"_remainingIterations": null,
"_status": {
"id": "ACTIVE"
},
"webhook": {
"id": "xxxxx-8ee7-xx-xxxx-x",
"event": "subscription-charge-in-24-hours",
"url": "https://example.com",
"logId": "xxxx-xxxxxxxxx-43c5-xxxx-xxx"
}
}
]
Use case
Next question is: when do we use webhooks? Let’s take a look at a real case…
Example:
Suppose your business sells programming courses, so you want to offer your customers a subscription plan to receive personalized content every month with exclusive insights and interviews with industry experts.
Now, imagine you're offering alternative payment methods, which can take some minutes between the cash transfer and the payment's approval. If you're managing access to this exclusive content through another application, you might want to wait until a Payment Status Change event notifies you that the payment has been approved, thus granting access to the content.
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".
