Register a webhook endpoint

The company administrator adds webhook endpoints in BIRP, not through the API. Each webhook endpoint has a URL, a list of events and a secret that signs every request.

Add a webhook endpoint

1. In BIRP, open Settings, then API, then the Webhooks tab.

2. Add a webhook endpoint: its URL, a description if you want one, and the events it receives.

3. Copy the signing secret. BIRP shows it once; keep it as a secret of your system, such as the environment variable BIRP_WEBHOOK_SECRET.

Rules for the URL

• An https URL on the standard port, without a user name or a password in it.

• A host name, not an IP address, that resolves only to public addresses. A request to any other address fails, and the domains of BIRP are refused.

• A company can have up to 10 webhook endpoints.

The URL of a webhook endpoint never changes. To use another URL, add a new webhook endpoint, then delete the old one.

Choose the events

Pick the events by resource: products, categories, customers, stock, orders and invoices. Webhook events says when each one is sent. You can change the list later.

To follow every change of a record, choose all the events of its resource. An update made together with another event of the record, such as a confirmation, comes only as that event.

Send a test event

From the page of the webhook endpoint in BIRP, send a test event. It has the type webhook.test and a fixed data, goes only to that webhook endpoint, and is tried once.

{
  "api_version": "v1",
  "data": {
    "message": "Test event sent from BIRP. It carries no record."
  },
  "id": "00000000-0000-4000-8000-000000000117",
  "occurred_at": "2026-09-28T14:05:12.417Z",
  "type": "webhook.test"
}

Its result appears in the list of deliveries on the same page, with the status your system answered.

Rotate the secret

Rotating creates a new secret, which BIRP shows once. For 24 hours BIRP signs each request with both secrets, the new one first, so you can update your system without missing events.

Pause, resume or delete

• A paused webhook endpoint receives nothing. Its events wait for up to 7 days and go out when you resume it.

• A deleted webhook endpoint receives nothing more, and the events waiting for it are dropped.

Related

• webhooks-overview
• verify-webhook-signatures
• webhook-events
• webhook-retries