Receive events with webhooks

Webhooks push events to your server in real time so you don't have to poll the API. Register an endpoint and react to events like new members, completed lessons, or new payments.

1. Register an endpoint

1. Go to Admin → API Keys → Webhooks (or the Webhooks tab in Admin).
2. Click Add endpoint and enter a public HTTPS URL (e.g. https://yourapp.com/hooks/bonfire).
3. Select the events to subscribe to.
4. Copy the generated signing secret — you'll use it to verify deliveries.

2. Handle the delivery

Bonfire sends a POST with a JSON body:

{
  "id": "evt_1a2b3c",
  "type": "member.joined",
  "created_at": "2026-05-29T10:00:00Z",
  "data": { "member_id": "mem_123", "email": "[email protected]" }
}

Respond with 2x quickly. Non-2x responses are retried with exponential backoff.

3. Verify the signature

Each request carries an X-Bonfire-Signature header (HMAC-SHA256 of the raw body using your signing secret). Always verify before trusting the payload:

import crypto from "crypto";

function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Reject requests that fail verification with 401.

Common events

Related

• Authenticate with the Bonfire API
• Rate Limits and Errors
• API Design Principles

FAQ

What if my endpoint is down? Failed deliveries retry with backoff. Use the delivery log in Admin to replay events.

How do I avoid processing the same event twice? Deliveries are at-least-once. Deduplicate on the event id.

Do webhooks need an API key? No — they push to you. Verify the signature instead.

Can I have multiple endpoints? Yes. Register several, each with its own event selection and secret.