Webhooks

Webhooks push EventOS activity to a URL you control. Use them when your systems need to react in real time—CRM updates, Slack alerts, custom badges—without polling the UI.

If you are not a developer (or do not have an engineering partner), you can skip this page. Widgets and the hosted site cover most organizer needs.

Where to manage webhooks

Open the event workspace and go to Developers → Webhooks. The console has four tabs:

Event types

Deliveries use these event names:

Event type	When it fires
registration.created	Someone completes signup
registration.cancelled	A registration is cancelled or refunded
payment.succeeded	A paid order is confirmed
payment.refunded	A payment is refunded
checkin.completed	An attendee is checked in
checkpoint.redeemed	Food, goodies, or an addon is claimed at a station

Leave Subscribed events empty when creating an endpoint to receive every event type. Selecting specific events filters deliveries to that list.

Create an endpoint

1. Prepare a receiver

   Stand up an HTTPS URL that accepts POST with a JSON body. For local development, http://127.0.0.1:… or a tunnel (for example ngrok) also works.

2. Add endpoint

   In Developers → Webhooks, click Add endpoint. Enter the URL and an optional description.

3. Choose events

   Leave events empty for all types, or expand categories (Registration, Payment, Check-in, Checkpoint) and select specific events.

4. Enable and create

   Keep Enabled on so deliveries start immediately. Optionally open Advanced to enable endpoint throttling, then click Create endpoint.

After creation, EventOS generates a signing secret (whsec_…). Open the endpoint to view, copy, or rotate it.

Endpoint detail

Each endpoint has three tabs:

Overview

• Delivery stats for the last 24 hours
• Signing secret (view, copy, rotate)
• Message attempts table with status, HTTP response, event type, duration, and Resend
• Sidebar metadata: created / updated times, endpoint ID, throttling, subscribed events

Use Edit to change the URL, description, subscribed events, or enabled state. Use Replay → Recover failed messages to re-queue recent failed deliveries. Disable or Delete are under the more-actions menu.

Testing

Pick an event type and click Send example. EventOS queues a sample payload so you can verify your receiver without placing a real registration.

Advanced

• Custom headers — extra headers sent with every delivery (signing headers cannot be overridden)
• Endpoint throttling — store a per-second cap for the endpoint
• Transformation — code editor for a future payload rewrite; stored for editing, not executed on delivery yet

Payload shape

Every delivery is a JSON POST body shaped like:

{
  "id": "evt_…",
  "type": "registration.created",
  "createdAt": "2026-10-05T12:00:00.000Z",
  "data": {
    "eventId": "…",
    "…": "event-specific fields"
  }
}

Test deliveries from the Testing tab include "test": true inside data.

Headers and signatures

Each request includes:

Header	Purpose
Content-Type	application/json
User-Agent	{Brand}-Webhooks/1.0
X-{Brand}-Event	Event type (for example registration.created)
X-{Brand}-Delivery	Delivery id
X-{Brand}-Timestamp	Unix timestamp (seconds) used in the signature
X-{Brand}-Signature	t={timestamp},v1={hmac}

{Brand} is your platform header brand (for EventOS this is typically Eventos, so X-Eventos-Signature).

Verify the signature

1. Read t and v1 from X-{Brand}-Signature.
2. Compute HMAC-SHA256 of `${t}.${rawBody}` using your endpoint signing secret.
3. Compare the hex digest to v1 (use a constant-time compare).
4. Optionally reject requests whose t is too far from your server clock.

Keep endpoints idempotent. Deliveries may be resent from the UI, and workers may retry after failures.

Test a delivery

1. Point at a receiver

   Use webhook.site, a local echo server, or your staging API.

2. Create or open the endpoint

   Confirm the URL is correct and the endpoint is Enabled.

3. Send an example

   On the endpoint Testing tab, choose an event type and click Send example.

4. Check results

   Confirm the request on your receiver, then refresh Message attempts (or the Logs tab) for status, HTTP code, and duration.

You can also trigger a real registration, payment, check-in, or checkpoint redemption and watch the matching event type appear in the logs.

Security checklist

Also:

• Prefer HTTPS in production
• Do not put the webhook URL or signing secret in client-side code
• Log deliveries while you integrate, then keep failed-delivery alerts on your side
• Treat duplicate id values as already processed