Webhook Configuration

This guide explains how to declare a webhook endpoint in Beedeez and describes the delivery contract your endpoint must work with.

Accessing Webhook Configuration

Webhook endpoints are configured in the Beedeez back office, under Configuration, Integrations, Webhooks. The page requires the Webhooks option on your account (enabled by Beedeez) and the right to update the account customization.

Adding or editing an endpoint only updates the screen: the configuration is written when you click Save all.

Creating a Webhook Endpoint

Required Fields

Name

A label to identify the endpoint in the list. It has no effect on delivery.

Example: "HR System Integration"

URL

The address Beedeez calls with a POST request. The back office does not validate it and does not test it on save, so check it carefully.

Recommendations:

• Use HTTPS
• Make it publicly reachable from the internet
• Respond within 5 seconds with an HTTP 2xx status

Example: https://api.example.com/webhooks/beedeez

Event Types

The events this endpoint subscribes to. See the Event Types Reference.

The form offers two event types:

• certificate_completed: sent when a certificate award is recorded, and also when an award reaches its expiry date
• certificate_expired: selectable, but never emitted

Subscribe to certificate_completed, whether you care about awards, expiries or both. An endpoint subscribed only to certificate_expired receives nothing.

Optional Configuration

Enabled

Each endpoint has its own switch. Only endpoints that are enabled and subscribed to the event are called.

Default: true

The page also shows a global Enable webhooks switch. It is not checked at send time: to stop deliveries, disable or delete each endpoint, then save.

Timeout (ms)

The form lets you enter a timeout and saves it, but deliveries do not use it: Beedeez always waits 5 seconds for your response.

Authentication

How Beedeez authenticates with your endpoint. See Authentication Options.

Available Methods:

• None
• Bearer Token
• Basic Auth
• API Key
• Custom Header (a single header name and value)

Custom Headers

The back-office form has no field for additional headers. The endpoint configuration can hold custom headers, which are then sent with each request, but only Beedeez can set them, and editing the endpoint in the back office afterwards removes them. For a shared secret, use the Custom Header authentication method instead.

Configuration Example

The endpoint configuration saved by the back office looks like this:

{
    "name": "HR System Integration",
    "url": "https://api.example.com/webhooks/beedeez/certificates",
    "enabled": true,
    "eventTypes": ["certificate_completed"],
    "auth": {
        "authType": "bearer_token",
        "token": "your-secret-bearer-token"
    }
}

Webhook Delivery

Request Format

• Method: POST
• Content-Type: application/json
• Body: the certificate award as JSON, with no envelope (no event name, delivery identifier or send timestamp). See Payload Examples.
• Headers: Content-Type, any custom headers, and the header of your authentication method. Authentication headers are applied last, so they overwrite a custom header of the same name.

Beedeez does not sign requests: no signature header is sent.

One request is sent per award and per subscribed endpoint, without batching. A catch-up pass that creates many awards at once produces as many requests in a short burst.

Response Requirements

Your endpoint should:

1. Respond within 5 seconds. Beedeez aborts the request after 5 seconds.
2. Return a 2xx status (200-299) to acknowledge receipt. Any other status, a timeout or a network error counts as a failure.
3. Be idempotent. The same award can reach you more than once.

Successful Response Example:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "received": true
}

The response body is ignored.

No Retry

Beedeez does not retry failed deliveries. A failure is logged on the Beedeez side and the notification is dropped; nothing replays it later, and your status code has no effect on what happens next.

If you cannot afford to lose an event, reconcile periodically with the public API: GET /v1/certificates with the updatedSince parameter returns the awards changed since your last sync.

Ordering and Parallelism

Deliveries are processed in parallel. Two notifications can reach you in a different order from the one in which the events occurred.

Best Practices

Security

• Use HTTPS endpoints
• Always configure an authentication method: it is the only proof that a request comes from Beedeez
• Treat the URL and the credential as secrets, and rotate them if they leak

Reliability

• Deduplicate on the award _id
• Store received payloads for audit
• Acknowledge first, then process in a queue or background job
• Reconcile through the API to recover deliveries that failed

Testing

• Test your endpoint with the sample payloads in Payload Examples
• Verify that authentication is accepted
• Trigger a real certificate award on a test account and watch what reaches your endpoint: there is no test button and no delivery history in the back office

Monitoring Webhook Status

The back office does not track deliveries. The success and failure counters shown on each endpoint are never updated and stay at zero. Monitor deliveries from your own endpoint logs.

Troubleshooting

Webhooks Not Being Received

1. Check the event type: the endpoint must be subscribed to certificate_completed
2. Check the endpoint switch: the endpoint itself must be enabled, and the configuration saved with Save all
3. Check the trigger: only certificate rules emit; gamification badges do not
4. Check accessibility: the URL must be reachable from the internet and accepted by your firewall
5. Check authentication: an incomplete credential (Basic Auth without both username and password, Bearer Token or API Key without a token) is sent without any authentication header

Webhooks Timing Out

1. Respond immediately: acknowledge with a 2xx before doing any processing
2. Use background processing: move heavy work to a queue
3. Check server resources: a request that is not answered within 5 seconds is lost

Duplicate Webhooks

The same award can occasionally be delivered more than once. Design your handler to be idempotent:

• Use the award _id together with expiryReminderSent as the deduplication key (the expiry notification reuses the _id of the original award)
• Store processed keys in a database
• Skip processing when the key was already handled

Next Steps

• Review Event Types to understand what is emitted
• Learn about Authentication Options
• See Payload Examples for sample data structures