Skip to content

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.

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.

  1. Open Settings and choose Developers. Open the Webhooks tab.
  2. Click to add an endpoint.
  3. Enter the https address of your server.
  4. Choose the events you want. Add a description if you like.
  5. Save the endpoint.
  6. 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. Plain http does 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.

You choose the events for each endpoint. There are 8.

EventWhen it is sent
registration.createdA signup is confirmed. A free signup counts at once. A paid signup counts after the payment.
registration.cancelledA confirmed signup ends. The member cancels, the host cancels the date or event, or a refund ends it.
member.joinedA person joins the club.
member.updatedA 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.leftAn admin removes a member.
event.createdAn event is published.
event.updatedAn event changes.
event.cancelledA 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.

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.

EventsPermissions needed
registration.created, registration.cancelledCan see all events and Check In Attendees
member.joined, member.updated, member.leftView Members
event.created, event.updated, event.cancelledCan 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.

Every message is JSON. It has the same four fields.

{
"id": "msg_2Hq8rT5vK1mXc9LwP3sNdZa7",
"type": "registration.created",
"timestamp": "2026-11-12T01:30:00.000Z",
"data": {}
}
FieldMeaning
idThe message id. It matches the webhook-id header.
typeThe event name.
timestampWhen Crewcade made the message. An ISO-8601 time in UTC.
dataIds that point to the thing that changed. It depends on type.
{
"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
}
}
  • memberId is null when the person holds no membership.
  • seriesId is null for a one-off event.
  • source says why the signup changed. It can be null.
{
"id": "msg_9Bd4fGh2JkLm6NpQr8StVw1X",
"type": "member.updated",
"timestamp": "2026-11-12T02:00:00.000Z",
"data": {
"memberId": "mem_456",
"source": null
}
}
{
"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.

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.

Use the ids to read the current state with your API key.

Terminal window
curl https://api.crewcade.com/api/v1/events/k3m9x2pq \
-H "Authorization: Bearer cck_your_key_here"

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.

HeaderMeaning
webhook-idThe message id. It is the same on every retry.
webhook-timestampWhen Crewcade sent the request. Seconds since 1970.
webhook-signatureThe signature. It looks like v1, and then base64. Two signatures are separated by a space.

To check a message:

  1. Read the raw body of the request. Do not parse it and write it again.
  2. Join webhook-id, webhook-timestamp and the raw body with a dot between each. The result is ${id}.${timestamp}.${rawBody}.
  3. Make an HMAC-SHA256 of that text. The key is the part of your secret after whsec_, decoded from base64.
  4. Encode the result in base64. Compare it with each v1 signature.
  5. 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.

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.

TryWhen
1Right away
25 seconds after try 1
35 minutes after try 2
430 minutes after try 3
52 hours after try 4
65 hours after try 5
710 hours after try 6
810 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 /v1 instead 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 /v1 now and then to catch up.

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.

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.

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.test message 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.

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 pathWhat it does
GET /webhook-endpointsList your endpoints, newest first.
POST /webhook-endpointsAdd 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}/enableTurn the endpoint on.
POST /webhook-endpoints/{endpointId}/disableTurn the endpoint off.
POST /webhook-endpoints/{endpointId}/rotate-secretMake a new secret. The old one works for 24 hours.
POST /webhook-endpoints/{endpointId}/testSend a test message.
GET /webhook-endpoints/{endpointId}/deliveriesList 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}/resendSend a finished delivery again.

Add an endpoint:

Terminal window
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.

StatusCodeMeaning
400webhook_url_https_requiredThe address does not use https.
400webhook_url_blocked_addressThe address is private, local or internal.
400webhook_url_credentials_forbiddenThe address has a user name or password.
400webhook_url_invalidThe address is not a valid web address.
400webhook_url_unresolvableThe address does not lead to a server.
403api_key_permission_missingThe key has no Manage Webhooks permission.
403webhook_permission_missingAn event needs a permission that the key or its creator does not hold.
403webhook_creator_permission_missingThe person who made the endpoint lacks a permission that an event needs.
409webhook_endpoint_limitThe club already has 10 endpoints.
409webhook_delivery_in_progressThe delivery is still being sent. Resend it after it finishes.
429webhook_send_limitedToo many tests or resends. Wait the seconds in the Retry-After header.
429rate_limitedToo many requests. Wait the seconds in the Retry-After header.

The 403 body lists missingPermissions.