Webhooks overview

Webhooks tell your systems when an order changes status in BillPro. BillPro sends an HTTPS POST request with a signed JSON document to a URL you choose. You don't need to poll the API for changes.

---

When to use webhooks

Use webhooks to keep another system in step with BillPro. For example:

• Update your order management system when an order becomes Active or Complete.
• Flag an account in your CRM when an order becomes Failed or Suspended.
• Post to your accounting system when an order is Complete or Cancelled.
• Start fulfilment when an order becomes Active, and hold it when an order is Paused.

Webhooks report order status changes. There are no separate events for individual payments, billing events, scheduled payments or refunds. A payment reaches you only when it changes the order's status, for example a declined payment that makes the order Failed.

---

How it works

1. In the dashboard, you add an endpoint: an HTTPS URL on your server, plus the order events you want.
2. BillPro creates a signing secret for the endpoint and shows it to you.
3. When an order moves into a status you subscribed to, BillPro sends a POST request to your URL. The body is a JSON document that describes the event.
4. BillPro signs each request with the secret. It puts the signature in the X-BillPro-Signature header.
5. Your server checks the signature, returns a 2xx status code, then processes the event.
6. If your server doesn't accept the request, BillPro retries it automatically for up to about 11 days. You can see every attempt in the endpoint's Recent deliveries log, and send any delivery again.

---

Order events

You can subscribe an endpoint to any of these events, or to all of them.

There is also order.test. BillPro sends it only when you click Send test event. You can't subscribe to it.

For what each status means for each order type, see Webhook events and order statuses.

---

Delivery rules to build for

• At least once. The same event can reach you more than once. Use the X-BillPro-Delivery header to spot repeats.
• No set order. Events can arrive in a different order from the one they happened in.
• HTTPS only. BillPro only sends to public https:// addresses.
• Signed. Check the signature on every request before you trust it.

See Handle webhook deliveries for how to deal with each rule.

---

Who can set up webhooks

You need an Admin user with API Access turned on. To turn on API Access, contact BillPro. See Manage users.

If your user isn't an Admin or doesn't have API Access, the Webhooks option doesn't appear in the menu.

Set up and manage webhooks in the dashboard.