Webhooks
A webhook is a message that Crewcade sends to your server. It arrives when something changes in your club. A member signs up for an event. A member joins. An event changes. You do not need to ask again and again.
Each message holds ids only. It never holds a name or an email. Your server reads the details with the Members, Events and Registrations endpoints.
Add an endpoint
Section titled “Add an endpoint”An endpoint is a web address on your server. It also lists the events you want. Owners and admins can add endpoints. Any role with the Manage Webhooks permission can too.
- Open Settings and choose Developers. Open the Webhooks tab.
- Click to add an endpoint.
- Enter the
httpsaddress of your server. - Choose the events you want. Add a description if you like.
- Save the endpoint.
- Copy the secret. It starts with
whsec_.
Crewcade shows the secret once. Store it somewhere safe. Your server uses it to check each message.
You can add up to 10 endpoints in one club. The club owners get an email for each new endpoint.
Endpoint address rules:
- Use
https. Plainhttpdoes not work. - Use an address on the public internet. Private, local and internal addresses are refused.
- Crewcade does not follow redirects. Give the final address.
- Do not put a user name or password in the address.
- The address can have up to 2048 characters.
Events
Section titled “Events”You choose the events for each endpoint. There are 8.
| Event | When it is sent |
|---|---|
registration.created | A signup is confirmed. A free signup counts at once. A paid signup counts after the payment. |
registration.cancelled | A confirmed signup ends. The member cancels, the host cancels the date or event, or a refund ends it. |
member.joined | A person joins the club. |
member.updated | A member changes. This covers profile, photo, social links, club fields and roles. It also covers suspend and unsuspend, an approved join, and the end of a membership seat. |
member.left | An admin removes a member. |
event.created | An event is published. |
event.updated | An event changes. |
event.cancelled | A whole event, one date, is cancelled. Unpublishing or deleting an event also sends it. |
Drafts never send a message. An event.updated message can arrive right after event.created.
Crewcade also sends a webhook.test message when you click Send test. You cannot choose it as an event.
Permissions
Section titled “Permissions”The person who made the endpoint must hold these permissions. For an API key, the key and the person who made it must hold them.
| Events | Permissions needed |
|---|---|
registration.created, registration.cancelled | Can see all events and Check In Attendees |
member.joined, member.updated, member.left | View Members |
event.created, event.updated, event.cancelled | Can see all events |
If the person loses a permission, Crewcade stops sending the events that need it. A member.updated message can change only sensitive fields. Crewcade sends it only when the person can see sensitive member data.
The message
Section titled “The message”Every message is JSON. It has the same four fields.
{ "id": "msg_2Hq8rT5vK1mXc9LwP3sNdZa7", "type": "registration.created", "timestamp": "2026-11-12T01:30:00.000Z", "data": {}}| Field | Meaning |
|---|---|
id | The message id. It matches the webhook-id header. |
type | The event name. |
timestamp | When Crewcade made the message. An ISO-8601 time in UTC. |
data | Ids that point to the thing that changed. It depends on type. |
Registration events
Section titled “Registration events”{ "id": "msg_2Hq8rT5vK1mXc9LwP3sNdZa7", "type": "registration.created", "timestamp": "2026-11-12T01:30:00.000Z", "data": { "registrationId": "reg_123", "memberId": "mem_456", "seriesId": "ab12cd34", "occurrenceId": "k3m9x2pq", "source": null }}memberIdisnullwhen the person holds no membership.seriesIdisnullfor a one-off event.sourcesays why the signup changed. It can benull.
Member events
Section titled “Member events”{ "id": "msg_9Bd4fGh2JkLm6NpQr8StVw1X", "type": "member.updated", "timestamp": "2026-11-12T02:00:00.000Z", "data": { "memberId": "mem_456", "source": null }}Event events
Section titled “Event events”{ "id": "msg_4Yc7ZaB1dEf3GhJ5KmN8PqRs", "type": "event.updated", "timestamp": "2026-11-12T03:00:00.000Z", "data": { "seriesId": "ab12cd34", "occurrenceId": "k3m9x2pq", "source": "details" }}source is one of created, published, time_or_location, details, series_split, host, schedule_edit, unpublished or deleted.
Series and dates
Section titled “Series and dates”A recurring event has many dates. Each date has its own 8-character occurrenceId. This is the same id that GET /events returns. All dates share one seriesId. See Dates, series and ids.
occurrenceId is null when the whole series changed. Call GET /events?seriesId= with the seriesId to read all its dates.
Read the details
Section titled “Read the details”Use the ids to read the current state with your API key.
curl https://api.crewcade.com/api/v1/events/k3m9x2pq \ -H "Authorization: Bearer cck_your_key_here"Check the signature
Section titled “Check the signature”Crewcade signs every message. Check the signature before you trust a message. Anyone can send a request to your address. Only Crewcade has your secret.
Crewcade follows the Standard Webhooks rules. Each request has three headers.
| Header | Meaning |
|---|---|
webhook-id | The message id. It is the same on every retry. |
webhook-timestamp | When Crewcade sent the request. Seconds since 1970. |
webhook-signature | The signature. It looks like v1, and then base64. Two signatures are separated by a space. |
To check a message:
- Read the raw body of the request. Do not parse it and write it again.
- Join
webhook-id,webhook-timestampand the raw body with a dot between each. The result is${id}.${timestamp}.${rawBody}. - Make an HMAC-SHA256 of that text. The key is the part of your secret after
whsec_, decoded from base64. - Encode the result in base64. Compare it with each
v1signature. - Reject the request if the timestamp is more than 5 minutes old.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyWebhook(headers, rawBody, secret) { const id = headers['webhook-id']; const timestamp = headers['webhook-timestamp']; const signatures = String(headers['webhook-signature']).split(' ');
const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp)); if (!id || !timestamp || ageSeconds > 300) return false;
const key = Buffer.from(secret.replace('whsec_', ''), 'base64'); const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest();
return signatures.some((signature) => { const [version, value] = signature.split(','); if (version !== 'v1' || !value) return false; const actual = Buffer.from(value, 'base64'); return actual.length === expected.length && timingSafeEqual(actual, expected); });}Use the raw body. Your framework can parse the body and write it again. The new text can differ from the original. Then the check fails.
You can also use the official libraries from standardwebhooks.com. They check the signature and the timestamp for you.
Delivery and retries
Section titled “Delivery and retries”Answer with a 2xx status within 10 seconds. Do your own work after you answer. Any other answer, or no answer, counts as a failure.
Crewcade tries again after a failure. It makes up to 8 tries in about 27 hours.
| Try | When |
|---|---|
| 1 | Right away |
| 2 | 5 seconds after try 1 |
| 3 | 5 minutes after try 2 |
| 4 | 30 minutes after try 3 |
| 5 | 2 hours after try 4 |
| 6 | 5 hours after try 5 |
| 7 | 10 hours after try 6 |
| 8 | 10 hours after try 7 |
Plan for these facts:
- Every retry and every resend uses the same
webhook-id. Save the ids you handled. Drop a message that you saw before. - Messages can arrive in the wrong order. Read the current state from
/v1instead of trusting the order. - Each message arrives at least once. It can arrive twice.
- A rare message can be missed. Read your members and events from
/v1now and then to catch up.
When an endpoint keeps failing
Section titled “When an endpoint keeps failing”An endpoint that fails for 5 days turns off. The club owners get an email. Fix your server. Turn the endpoint on. Then send the missed messages again from the delivery log.
Revoking an API key also turns off the endpoints that this key made.
Replace the secret
Section titled “Replace the secret”Click to rotate the secret on the endpoint page. Crewcade shows the new secret once. The old secret keeps working for 24 hours. During this time each request carries two signatures. Your server can switch to the new secret without missing a message.
Delivery log
Section titled “Delivery log”Open an endpoint to see its deliveries. Crewcade keeps 30 days. Each delivery shows every try with its status code, time and duration. It also shows the first 1 KB of your reply.
- Click Resend to send a finished delivery again.
- Click Send test to send a
webhook.testmessage to your endpoint.
You can send up to 10 tests or resends each minute for one endpoint. You can send up to 100 each day for the whole club.
Manage endpoints with the API
Section titled “Manage endpoints with the API”These calls need an API key with the Manage Webhooks permission (can_manage_webhooks). A key can only pick events that the key and its creator may receive.
| Method and path | What it does |
|---|---|
GET /webhook-endpoints | List your endpoints, newest first. |
POST /webhook-endpoints | Add an endpoint. The reply has the secret once. |
GET /webhook-endpoints/{endpointId} | Read one endpoint. |
PATCH /webhook-endpoints/{endpointId} | Change the address, the description or the events. |
DELETE /webhook-endpoints/{endpointId} | Delete the endpoint and its delivery log. |
POST /webhook-endpoints/{endpointId}/enable | Turn the endpoint on. |
POST /webhook-endpoints/{endpointId}/disable | Turn the endpoint off. |
POST /webhook-endpoints/{endpointId}/rotate-secret | Make a new secret. The old one works for 24 hours. |
POST /webhook-endpoints/{endpointId}/test | Send a test message. |
GET /webhook-endpoints/{endpointId}/deliveries | List deliveries of the last 30 days. |
GET /webhook-endpoints/{endpointId}/deliveries/{deliveryId} | Read one delivery with every try and the sent body. |
POST /webhook-endpoints/{endpointId}/deliveries/{deliveryId}/resend | Send a finished delivery again. |
Add an endpoint:
curl https://api.crewcade.com/api/v1/webhook-endpoints \ -X POST \ -H "Authorization: Bearer cck_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/hooks/crewcade", "description": "Sync signups", "eventTypes": ["registration.created", "registration.cancelled"] }'{ "endpoint": { "id": "whe_123", "url": "https://example.com/hooks/crewcade", "status": "enabled", "eventTypes": ["registration.created", "registration.cancelled"] }, "secret": "whsec_your_secret_here"}The reply shows more fields than this. See the OpenAPI spec.
Errors
Section titled “Errors”| Status | Code | Meaning |
|---|---|---|
| 400 | webhook_url_https_required | The address does not use https. |
| 400 | webhook_url_blocked_address | The address is private, local or internal. |
| 400 | webhook_url_credentials_forbidden | The address has a user name or password. |
| 400 | webhook_url_invalid | The address is not a valid web address. |
| 400 | webhook_url_unresolvable | The address does not lead to a server. |
| 403 | api_key_permission_missing | The key has no Manage Webhooks permission. |
| 403 | webhook_permission_missing | An event needs a permission that the key or its creator does not hold. |
| 403 | webhook_creator_permission_missing | The person who made the endpoint lacks a permission that an event needs. |
| 409 | webhook_endpoint_limit | The club already has 10 endpoints. |
| 409 | webhook_delivery_in_progress | The delivery is still being sent. Resend it after it finishes. |
| 429 | webhook_send_limited | Too many tests or resends. Wait the seconds in the Retry-After header. |
| 429 | rate_limited | Too many requests. Wait the seconds in the Retry-After header. |
The 403 body lists missingPermissions.