Set up a webhook endpoint

Add an endpoint to start receiving order events at your server. You can add several endpoints to a profile, each with its own URL, events and signing secret.

---

Before you start

• An Admin user with API Access turned on. To turn on API Access, contact BillPro.
• A public https:// URL on your server that accepts POST requests.
• Code on that URL that verifies signatures. See Verify webhook signatures.

Endpoints belong to a merchant profile. Check that you are in the right profile before you start.

---

Endpoint requirements

You don't need to send a test before the endpoint goes live. A new endpoint receives events as soon as you save it, unless you set it to Inactive.

---

Add an endpoint

1. From the user icon menu, select Webhooks.

2. Click Add endpoint. If the profile has no endpoints yet, click Add your first endpoint.

3. On the Add Webhook Endpoint screen, leave the status as Active. Choose Inactive if you want to set up the endpoint now and receive events later.

4. In Destination, enter the Endpoint URL.

5. Optional: enter a Description, for example "ERP order sync". Keep it under 255 characters.

6. In Order events, choose what to receive:

   • Turn on Enable all order events to receive every order event, including any that BillPro adds later.

   • Or check the events you want: Draft, Registered, Rejected, Failed, Active, Review, Cancelled, Complete, Pending, Paused, Suspended. Choose at least one.

7. Click Add Endpoint.

BillPro shows the Webhook Endpoint Created screen with your signing secret.

---

Save the signing secret

The secret starts with whsec_. Your server uses it to check that each request came from BillPro.

1. Under Your signing secret, click the copy button beside the secret.
2. Store it where your server can read it, such as an environment variable or a secrets manager. Don't commit it to source control.
3. Click View endpoint to open the endpoint, or Back to Webhooks to return to the list.

To see the secret later:

1. From the user icon menu, select Webhooks, then click the endpoint URL.
2. In Signing secret, click Reveal. Click Hide when you're done.

---

Send a test event

Send a test to check that your server receives and verifies requests.

1. Open the endpoint from the Webhooks list.

2. In Recent deliveries, click Send test event.

3. BillPro queues an order.test event. The new row appears at the top of Recent deliveries with the status Pending.

4. Refresh the page after a few seconds. The status changes to Succeeded when your server returns a 2xx code. The Response column shows the status code your server returned.

A test delivery isn't linked to an order, so the UID column shows a dash. The payload still carries an order, so your parser gets the full shape:

• Until the endpoint has accepted one delivery, it's a sample order with made-up details.
• After that, it's the most recent real order on the profile.

Your server should accept order.test with a 2xx code and take no action, even though the order in it may be real.

---

Edit an endpoint

You can change the URL, description, events and status. Editing doesn't change the signing secret.

1. Open the endpoint from the Webhooks list.
2. Click Edit.
3. Change the fields you need.
4. Click Save.

To replace an endpoint with a new URL, edit the URL. The endpoint keeps its secret and delivery log. To get a new secret, rotate it. The endpoint keeps its URL, events, status and delivery log. See Rotate a webhook signing secret.

---

Turn an endpoint on or off

1. Open the endpoint and click Edit.
2. Set the status to Active or Inactive.
3. Click Save.

When you set an endpoint to Inactive, BillPro stops sending to it. It also cancels every delivery that is waiting to be sent or retried. Those deliveries show the status Canceled. Deliveries that already finished aren't changed.

When you set the endpoint back to Active, canceled deliveries stay Canceled. BillPro doesn't resume them. Use Send again on each one you still need.

If BillPro switched the endpoint off after repeated failures, the status shows Auto-disabled, and BillPro emails the merchant. Fix the problem on your server, then set the status back to Active. See Handle webhook deliveries.

---

Delete an endpoint

1. Open the endpoint.
2. Click Delete.
3. Confirm with Delete.

BillPro stops sending events to the URL.