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 POSTrequest 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 using payment_order or expected_payment.
  • event Specifies what happened to the object.
  • data Contains the updated object that changed.
{
  "category": "object_type",
  "event": "event_type",
  "data": {
    // serialized object
  }
}
CategoryDescription
expected_paymentAny expected payment lifecycle event.
payment_orderAny payment order lifecycle event.
mandatesAny mandates lifecycle event (coming soon).

Please see our Expected Payments Webhooks.