Webhooks

Send outgoing HTTP callbacks to your own systems when events happen on the platform (order completed, winner drawn, prize fulfilled, etc.).

Route

/admin/webhooks

Overview

The webhook system publishes events asynchronously via BullMQ. Each delivery is signed with HMAC-SHA256 so your receiving endpoint can verify authenticity. Failed deliveries are retried automatically with exponential backoff and logged for inspection.

Managing Webhooks

Webhook List

The index page shows all configured webhooks:

• Name — Human-readable label
• URL — Destination endpoint
• Events — Which events trigger this webhook
• Status — Active / Paused
• Last Delivery — Timestamp + success/failure indicator
• Actions — Edit, pause, delete, view deliveries

Creating a Webhook

1. Click New Webhook (/admin/webhooks/new)
2. Fill in:
   • Name — e.g. "Fulfilment CRM sync"
   • URL — HTTPS endpoint that will receive deliveries
   • Events — Tick one or more event types to subscribe to
   • Secret — Auto-generated HMAC secret (copy it now; it won't be shown again in full)
   • Active — Toggle off to create paused
3. Save

Editing a Webhook

/admin/webhooks/[id] — change URL, event subscriptions, pause state, or rotate the signing secret. Rotating the secret invalidates the old one immediately, so update your receiving endpoint first.

Event Types

Subscribe to any combination of:

• order.completed — Order paid and tickets issued
• order.refunded — Refund processed
• winner.drawn — Competition draw completed (fires per winner)
• winner.prize_choice_made — Winner selected a prize alternative
• withdrawal.requested / withdrawal.paid — Cash wallet withdrawals
• competition.created / competition.ended
• user.registered

The full event list is shown on the create/edit form with short descriptions.

Delivery Log

Each webhook has a delivery history panel showing recent attempts:

• Event — Event type + resource ID
• Status — HTTP status code or error
• Attempt — Which retry this is (1-6)
• Duration — Time to response
• Timestamp — When the attempt was made
• Actions — Inspect payload, inspect response, redeliver

Redelivery

Click Redeliver on a failed (or successful) attempt to re-send the exact same payload. Useful when your receiver was down and you want to backfill.

Signing

Every delivery includes an HMAC-SHA256 signature in the X-Comps-Signature header. Verify it on your side:

// Node.js example
import crypto from 'crypto'

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

• Always compare using a timing-safe comparator.
• Verify against the raw request body, not a re-serialised JSON string.
• Reject deliveries older than a few minutes to mitigate replay (the X-Comps-Timestamp header is included).

Retries

• Up to 6 attempts over roughly 30 minutes with exponential backoff
• Any 2xx response is considered success
• 4xx responses (except 408, 429) are not retried — treat them as your bug to fix
• 5xx and network errors are retried
• After the final attempt, the delivery is marked Permanently Failed and an alert email is sent to admins

Monitoring

• Delivery log on each webhook's page shows the last 100 attempts.
• Permanently failed deliveries trigger an admin email alert so no event is silently dropped.
• Pair with your own observability: the delivery payload includes the event ID so you can correlate with logs on your side.

Security

• Always use HTTPS — plain HTTP endpoints are rejected.
• Verify signatures — don't trust request bodies without HMAC verification.
• Rotate secrets if you suspect compromise — old signatures stop verifying immediately.
• Webhook secrets are stored encrypted at rest.

Common Use Cases

• CRM sync — Push new users / orders into HubSpot, Salesforce, etc.
• Fulfilment pipeline — Trigger picking/shipping when a physical prize is won.
• Accounting — Forward completed orders to your bookkeeping system.
• Slack/Teams alerts — Ping a channel when a big win is drawn.
• Audit / archive — Mirror events into your own data warehouse.

Tips

• Start with a single event subscription, verify delivery end-to-end, then add more.
• Use the Redeliver button when testing your receiver — it's faster than replaying a real order.
• If you're receiving duplicates during a replay storm, key your processing by the event ID (each payload has a unique id).
• Failed webhooks don't block platform operations — your outage won't break checkout.