Overview

Welcome to the be-in webhook platform documentation. this section gives you a high-level understanding of how integration partners can generate qr codes for pod access and receive entry notifications.

what are webhooks?

webhooks are outbound http callbacks that notify your backend in real-time when users scan qr codes and gain entry through be-in pods. instead of polling the api, you receive push-style updates when someone uses a qr code you generated.

the integration flow

1. your backend requests a qr code from be-in for a specific pod
2. end-user scans the qr code at a be-in pod (hardware device)
3. pod validates the qr code and grants access
4. be-in platform sends an entry.recorded webhook to your endpoint
5. your backend processes the entry notification

delivery model

1. a user scans a qr code at a pod, triggering an entry.recorded event
2. the platform synchronously loops through all allowed webhook endpoints for the integration partner (authorised per pod allow-list)
3. the backend emits an entry.recorded webhook (see payload below) to each subscribed endpoint via a single HTTP POST
4. your server must respond with an http 2xx status code within 3 s to mark the delivery as successful. any other status (or timeout) is logged as failed; no automatic retry
5. failures are logged and can be replayed manually via the dashboard or api

webhook envelope format

{
  "id": "<uuid>", // unique per delivery
  "type": "entry.recorded", // always this for now
  "created_at": "2024-05-31T12:34:56.789Z",
  "data": {
    "request_id": "bein_8N1r6W2XK", // your original request
    "pod_id": "uuid",
    "scanned_at": "iso-8601",
    "metadata": {
      /* your original metadata */
    },
  },
}

headers

reliability & ordering

• deliveries happen synchronously inside the same request that triggers the event. if your endpoint is slow, it slows down the user-facing flow—keep it fast.
• the platform does not guarantee ordering between different endpoints. within one endpoint, events are delivered in the order they were emitted.
• there is no automatic retry. you can replay failed deliveries from the dashboard or via the deliveries api.

the flow

next steps

• read the quick-start to set up your first integration.
• study security for signature verification.
• consult the event catalogue and api reference for full details.