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 type | When it fires |
|---|---|
| contact.created | A new contact is added to your organization. |
| registration.created | A golfer registers for one of your tournaments. |
| registration.paid | A registration payment is confirmed by Stripe. |
| invitation.delivered | An outbound invitation email is delivered to the recipient. |
Create a webhook endpoint
Open API access
Click API access in the top bar of your dashboard. Only admins see it. It opens Settings → API access.
Click + Add endpoint
Scroll to Webhooks and click + Add endpoint.
Enter your endpoint URL
It must be https. Add a description if you like.
Tick the events to send
Pick at least one: contact.created, registration.created, registration.paid or invitation.delivered.
Click Save endpoint
Copy the signing secret it shows. You need it to check signatures.
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:
- Parse t (Unix timestamp in seconds) and v1 (hex HMAC) from the header.
- Check that t is within 5 minutes of your current time to guard against replay attacks.
- Compute HMAC-SHA256 over the string t.<raw_body> using your signing secret as the key.
- 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 row | What it does |
|---|---|
| Show deliveries | Opens the delivery log for that endpoint. |
| Replay | On a delivery in the log, sends it again. You'll see Replay queued. |
| Rotate secret | Makes a new signing secret. Update your system with it. |
| Disable / Re-enable | Stops deliveries until you turn it back on. |
| Delete | Removes 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 this | Try this |
|---|---|
| Webhook URL resolves to a private address | Use a public https URL. For local testing, use a tunnel such as ngrok or Cloudflare Tunnel. |
| The endpoint was disabled | After 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.
