Skip to content
Developers3 min readUpdated October 27, 2026

Webhooks

Quick answer

Webhooks push events to your server so you don't have to poll. Click API access in the top bar, then + Add endpoint under Webhooks. Enter an https URL, tick at least one event (contact.created, registration.created, registration.paid or invitation.delivered) and click Save endpoint. Check each delivery with the HMAC-SHA256 signature in the X-ScrambleSync-Signature header.

On this page

Overview

Webhooks tell your system the moment something happens in ScrambleSync, like a new registration.

Who this is for

Developers connecting ScrambleSync to a CRM, mailing list or their own app.

Events you can subscribe to

Event typeWhen it fires
contact.createdA new contact is added to your organization.
registration.createdA golfer registers for one of your tournaments.
registration.paidA registration payment is confirmed by Stripe.
invitation.deliveredAn outbound invitation email is delivered to the recipient.

Create a webhook endpoint

  1. Open API access

    Click API access in the top bar of your dashboard. Only admins see it. It opens Settings → API access.

  2. Click + Add endpoint

    Scroll to Webhooks and click + Add endpoint.

  3. Enter your endpoint URL

    It must be https. Add a description if you like.

  4. Tick the events to send

    Pick at least one: contact.created, registration.created, registration.paid or invitation.delivered.

  5. Click Save endpoint

    Copy the signing secret it shows. You need it to check signatures.

Add endpoint form in the Webhooks section
1. Endpoint URL (https only) 2. Events to send 3. Save endpoint.

Payload envelope

Every delivery is an HTTP POST with Content-Type: application/json. The body has this shape: { "id": "<event_id>", "type": "registration.created", "created_at": "2026-06-08T15:30:00.000Z", "data": { … } } The data object contains the resource that triggered the event (for example, a registration object for registration.created).

Verifying the signature

Each delivery includes an X-ScrambleSync-Signature header of the form t=<unix_timestamp>,v1=<hex_hmac>. To verify:

  1. Parse t (Unix timestamp in seconds) and v1 (hex HMAC) from the header.
  2. Check that t is within 5 minutes of your current time to guard against replay attacks.
  3. Compute HMAC-SHA256 over the string t.<raw_body> using your signing secret as the key.
  4. Compare your computed hex digest to v1 using a constant-time comparison. Reject if they don't match.

Retries and failure handling

ScrambleSync retries failed deliveries with exponential backoff: after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, and 24 hours, up to 8 total attempts. If all 8 fail, the endpoint is automatically disabled with a disabled_reason of consecutive_failures. Re-enable it from Settings → API access once your endpoint is fixed, then replay missed deliveries.

Manage an endpoint

On the endpoint rowWhat it does
Show deliveriesOpens the delivery log for that endpoint.
ReplayOn a delivery in the log, sends it again. You'll see Replay queued.
Rotate secretMakes a new signing secret. Update your system with it.
Disable / Re-enableStops deliveries until you turn it back on.
DeleteRemoves the endpoint.

You can do the same through the API: POST /api/v1/webhooks/{id}/deliveries/{did}/replay and POST /api/v1/webhooks/{id}/rotate-secret (scope webhooks:write).

Tips

  • Return a 2xx right away and do the work in a queue.
  • Use the event id to skip duplicates when a delivery is retried.

Troubleshooting

If you see thisTry this
Webhook URL resolves to a private addressUse a public https URL. For local testing, use a tunnel such as ngrok or Cloudflare Tunnel.
The endpoint was disabledAfter 8 failed attempts we disable it. Fix your endpoint, click Re-enable, then replay what you missed.

Frequently asked questions

How do I handle a webhook that arrives more than once?

Use the event id field as an idempotency key. If you see the same id twice, it is a retry and you have already processed it, acknowledge it with 2xx but skip the business logic.

What should my endpoint return?

Return any 2xx HTTP status as quickly as possible (200 or 204 works). If processing takes time, queue the payload internally and return 2xx immediately, do not hold the connection open.

Can I test webhooks locally?

Yes. Use a tunneling tool (such as ngrok or Cloudflare Tunnel) to expose a local port, then register that URL as your endpoint. You can also replay historical deliveries from Settings → API access once your endpoint is registered.

My endpoint was turned off. How do I turn it back on?

Fix it so it returns 2xx, click Re-enable on the endpoint row, then use Show deliveries and Replay for anything you missed.