Overview

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 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 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 using payment_orders or expected_payments.
• type Specifies what happened to the object.
• data Contains the updated object that changed.

{
  "category": "object_type",
  "type": "event_type",
  "data": {
    // serialized object
  }
}

Please see our Expected Payments Webhooks.