When building integrations with Payable, you may want your applications to receive event notifications as they happen, to inform downstream actions in your own systems.
To enable webhook events, you first need to register webhook endpoints, which will receive event data.
To get set up, share your endpoints with us and we will register them for you.
Examples of when you may want to receive a webhook are; when a payment is successfully processed by your bank, or a customer pays an invoice.
Webhook signatures
A webhook signature is a security measure which allows you to verify that it is Payable who is sending the webhook. To authenticate the integrity of a webhook, each webhook contains a hash-based message authentication code (HMAC) in its Payable-Signature header.
Live vs Test
The endpoint URL where the message is sent to will depend on the API key used, whether it's live or test. Payable offers a Live vs. Test mode so you don't have to integrate to different endpoints for sandbox and production. If you want to use the same URL for both live and test webhooks, you can still differentiate using the HTTP header X-Live-Mode
which is true for live
traffic and false
for test traffic.
Technical Details
Payable notifications depend on the events
available. For each event, Payable will send a POST
request to your endpoint in a JSON format.
To acknowledge receipt of an event, your endpoint must respond with a 2xx HTTP status code to Payable within 5 seconds. If the endpoint takes longer to respond or returns an HTTP status code different from 2xx, the webhook will be re-sent at a later time using an exponential backoff strategy.
Webhook idempotency
Each webhook has an idempotency_key
field . This is passed through as the HTTP body. You can save these IDs as you process webhooks to ensure each webhook is only processed once. If a webhook is sent multiple times, its idempotency_key
will remain the same between requests.
Data Modeling
Payable Webhooks are structured with Categories, Events, and Data passed through the HTTP body.
category
Describes which category the event belongs to this will be the product you are usingpayment_orders
orexpected_payments
.type
Specifies what happened to the object.data
Contains the updated object that changed.
{
"category": "object_type",
"type": "event_type",
"data": {
// serialized object
}
}
Category | Description |
---|---|
expected_payments | Any expected payment lifecycle event. |
payment_orders | Any payment order lifecycle event. |
mandates | Any mandates lifecycle event (coming soon). |
Please see our Expected Payments Webhooks.