Configuring a webhook endpoint

Prerequisite: the Webhooks option on your account, which only Beedeez can turn on. Without it the page does not appear in the menu.

Rights required: the Update customization right, on the parent account. Without it the Configuration menu does not exist. The entry is also unavailable while a department is selected: switch back to the parent account.

A webhook makes Beedeez call a URL on your side when an event occurs. This page covers the configuration and the delivery contract. To find out which events are actually emitted, read Webhook events first: the form offers more of them than are sent.

Where it is set

Open the Configuration menu, Integrations section, Webhooks page. The screen opens on Global Settings and its Enable webhooks switch, followed by Webhook Endpoints and the Add Endpoint button. Each endpoint appears as an expandable row showing its name, its URL, its authentication type, its configured timeout and its event types. Expand a row to reach Edit and Delete.

The fields

The form ships in English whatever the interface language.

• Name: your own label. It helps you find the entry in the list and has no effect on delivery.
• URL: the address that gets called. No validation is applied: HTTPS is not required, the format is not checked, and the address is never tested on save. A wrong URL saves without a warning.
• Timeout (ms): how long Beedeez waits for your response. The value is saved and displayed on the endpoint row, and the sender applies it when it receives one. For the events emitted today it is not passed on, so the wait falls back to 5 seconds whatever you enter. Size your endpoint to answer within that window.
• Event Types: the events this endpoint subscribes to, shown as clickable tags. At least one is required.
• Authentication: the Type field offers None, Bearer Token, Basic Auth, API Key and Custom Header. Depending on your choice you fill in Token, Username and Password, or Header Name and Header Value. Bearer Token sends Authorization: Bearer, Basic Auth sends Authorization: Basic with your credentials encoded, API Key sends your token in the X-API-Key header, and Custom Header accepts a single name and value pair.

A credential that is left incomplete is silently skipped: Basic Auth without both a username and a password, or Bearer Token without a token, sends the request with no Authorization header at all. Your endpoint then sees an unauthenticated call rather than an error on the Beedeez side.

What Beedeez sends

A POST request with Content-Type: application/json. The only headers sent are that Content-Type, your custom headers, and the one carrying your chosen authentication mode.

⚠️ Authentication wins over a custom header of the same name. The authentication headers are applied last, so a custom header called Authorization or X-API-Key is overwritten by the authentication mode. Give your custom headers distinct names.

A 2xx response counts as acknowledged. Any other status, or no response within the timeout, counts as a failure.

⚠️ The body carries no event envelope. You receive the business object itself, with no event name, no send timestamp and no delivery identifier. If you need to tell two events apart, declare one endpoint per event and let the URL carry the distinction.

There is no signature

No signature is computed and none is sent: no secret field in the form, no signature header on the request, nothing for your receiver to verify. If your project expects an X-Hub-Signature-256 header, it expects something that never arrives.

💡 Treat the URL as a secret and always set an authentication mode. That credential is the only proof of origin you will get: anyone who knows the address can send you a fake event.

What it does not do

• No retry. A failed delivery is recorded as a failure and the job still finishes normally, so nothing replays it. The event is logged on the Beedeez side and then dropped. If you cannot afford to lose it, plan a periodic reconciliation through the API or an export.
• No delivery history, no test button. The ✓ and ✗ counters shown on each endpoint are never filled in and stay at zero. The only check available is to trigger a real event and watch what reaches you.
• No ordering guarantee. Deliveries go out in parallel, so two events can reach you out of order.
• No uniqueness guarantee. A delivery can be replayed internally. Make your processing idempotent: receiving the same event twice must produce the same result as once.
• No IP restriction.

The traps

Adding or editing an endpoint does not save it. The dialog only updates the screen; the configuration is written when you click Save all at the bottom of the left panel. Leaving the page first loses your input.

The Enable webhooks switch does not stop deliveries. At send time, Beedeez selects the endpoints that are individually enabled and subscribed to the event; the global switch is not part of that check. To cut deliveries off, turn off the switch on each endpoint or delete them, then save.

Going further

• Webhook events: the list that is really emitted, to read before writing any code.
• API, webhooks, callbacks: which to choose: the cases where a webhook is the wrong mechanism.
• Generating and revoking an API key: the reconciliation path when an event has been lost.
• Validity, expiry and renewal: what triggers the events available today.