Naturally, bank transfers and reconciling money do not take effect immediately. Normally the underlying system (the corporate bank account, or how often the payment data source is sent to Payable) operates asynchronously.
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 a unique ID. This is passed through as the HTTP header X-Webhook-ID
. 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 ID 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_order
orexpected_payment
.event
Specifies what happened to the object.data
Contains the updated object that changed.
{
"category": "object_type",
"event": "event_type",
"data": {
// serialized object
}
}
Category | Description |
---|---|
expected_payment | Any expected payment lifecycle event. |
payment_order | Any payment order lifecycle event. |
mandates | Any mandates lifecycle event (coming soon). |
Please see our Expected Payments Webhooks.