Webhooks

A webhook is the way e-bon pushes events to your systems the moment they happen — a receipt is issued, a command completes, a device goes offline, a Z report is generated. You give e-bon an HTTPS URL, pick which events you care about, and from then on every matching event is delivered to your endpoint as a signed JSON POST. No polling, no API calls from your side, no waiting. The full per-event payload reference, the four X-EBon-* HTTP headers and the HMAC SHA-256 signature verification flow live on the Webhook events page in the API reference — this Portal page is about how to configure an endpoint without writing any code.

Find your webhooks

Open the Portal sidebar and pick Settings → Webhooks. The page lives at /portal/settings/webhooks and lists every webhook endpoint currently registered for your organization, together with its URL, subscribed events, active/inactive state, last-delivery time and consecutive-failure count.

Create an endpoint

Copy the secret (one-time reveal)

The moment an endpoint is created — and again every time you rotate the secret — e-bon shows you the signing secret in a dedicated modal:

Use the copy button next to the secret to put it on your clipboard, then paste it into your secret store (1Password, Vault, your CI provider, etc.) before you click Done. The secret is what your receiving service uses to compute the HMAC SHA-256 signature in the X-EBon-Signature header on every incoming delivery. The full verification snippets — both Node.js and the openssl one-liner — live on the API reference: see Verify webhook signatures.

Manage existing endpoints

The list view on /portal/settings/webhooks shows one card per endpoint. Each card surfaces:

• The full URL (monospaced, click-to-copyable).
• An Active / Inactive badge driven by the enabled flag.
• The subscribed events as small primary-coloured badges.
• The Last delivery timestamp (relative — “2 minutes ago”, “3 hours ago”).
• A red failure-count strip when the endpoint has any consecutive failures (“3 failures”, “12 failures”) — the same failureCount the API exposes on the webhook record.

Three buttons sit on the right of each row:

• Send test (paper-plane icon) — see Send a test delivery.
• Edit (pencil icon) — opens the edit modal.
• Delete (red trash icon) — opens the delete confirmation modal.

Edit an endpoint

The Edit Webhook modal lets you change the URL, the description, the subscribed events and the Enabled toggle. The URL is validated against the same https:// rule as on create; the events list still requires at least one entry. Hit Save to persist the changes — no new secret is generated, so existing receivers keep working.

The same modal also has a Rotate secret button (see below) and a Recent Deliveries table at the bottom — a paginated, filterable view (status: All / Pending / Success / Failed) of the latest delivery attempts for this endpoint, showing the event type, status, HTTP response code, attempt number and timestamp. Use it to debug a misbehaving receiver: a row with status “Failed” and HTTP 500 tells you the endpoint is reachable but throwing; a row with status “Failed” and HTTP — usually means the request never connected (DNS / TLS / timeout).

Rotate the signing secret

Click Rotate secret in the edit modal to invalidate the current secret and generate a new one. The reveal modal opens immediately with the new secret — copy it, then update every receiver that verifies signatures.

Delete an endpoint

Click the red trash icon on any row to open the Delete Webhook modal. The modal asks: “Are you sure you want to delete the webhook <URL>? This action cannot be undone.” Click Delete to confirm.

Deletion is immediate: the endpoint is removed and no further events are dispatched to it. There is no undo. To pause an endpoint without throwing the configuration away, toggle Enabled off in the edit modal instead.

Send a test delivery

The paper-plane button on each row fires a synchronous test delivery to that endpoint with the canonical webhook.test event. The request body is exactly:

{
  "test": true,
  "message": "This is a test event from e-bon."
}

…wrapped in the standard envelope (see Inspect the event envelope) and signed with the endpoint’s current secret. The Portal waits for the receiver’s response and shows one of two toasts:

• Test webhook delivered successfully. — the receiver returned 2xx within the 10-second timeout.
• Test webhook failed: <error> — anything else (non-2xx response, timeout, connection error, TLS error). The error string is whatever the dispatcher reported.

The test does not require any of your subscribed events to be webhook.test — the test is always allowed regardless of the subscription list. Use it any time you want to confirm the URL is reachable, the TLS chain is valid and your signature verification accepts the current secret.

Handle auto-disable on persistent failures

e-bon retries failed deliveries automatically with exponential backoff. If an endpoint accumulates 20 consecutive failures, the subscription is automatically set to enabled: false and stops receiving new dispatches — you will see it switch to the red Inactive badge in the list. Re-enable it from the edit modal once the receiver is fixed.

The exact backoff schedule (5 attempts, ~10s timeout per attempt) and the auto-disable rule live on the API reference: see Handle retries.

Where to next

• Webhook events — per-event payload reference, the four X-EBon-* HTTP headers, the HMAC SHA-256 signature verification flow (Node.js + openssl), and the full delivery + retry schedule.
• Webhooks API — programmatic CRUD over webhook subscriptions using an API key (POST /api/v1/org/webhooks, PATCH /…/{id}, DELETE /…/{id}, POST /…/{id}/test, POST /…/{id}/rotate-secret).
• API keys — the read-side credential. API keys pull data; webhooks push events. Most integrations use both.
• Billing — manage your organization’s subscription and invoices.