Receive and verify signed webhooks

Register your endpoint

Call POST /webhooks under your discovered workspace base with a public HTTPS url and supported events. Save the returned signing_secret once as a secret.

curl "$BASE/webhooks" -X POST \
  -H "Authorization: Bearer $CRICKETS_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://your-service.example/crickets","events":["post.published","delivery.failed","media.ready"]}'

Webhooks belong to the credential/integration that creates them. Public HTTPS endpoints are required; redirects and private-network destinations are rejected.

Verify before processing

Events contain a stable id, type, workspace_id, created_at, and resource identifiers/statuses in data. Preserve the exact raw request body before parsing JSON.

1. Read Crickets-Signature, formatted as t=timestamp,v1=base64url_signature.
2. Reject timestamps more than five minutes from your server’s clock. Keep the clock synchronized.
3. Calculate HMAC-SHA256 of timestamp + "." + raw_request_body with the signing secret. Decode the received base64url signature and compare bytes in constant time.
4. Only after verification, parse the JSON and deduplicate by event ID. Queue the work durably and return a 2xx promptly.

Supported events

• post.created
• post.updated
• post.draft
• post.scheduled
• post.publishing
• post.published
• post.partial
• post.failed
• delivery.published
• delivery.failed
• delivery.blocked
• delivery.needs_review
• media.ready
• account.reconnect_required

Use GET /webhooks and PATCH /webhooks/{id} to inspect or update your integration’s webhook. Disable it when you want to pause that endpoint.

Retries, replay and access

An event can arrive more than once. Your handler must safely ignore event IDs it has already processed. Retry delays are 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours.

Inspect deliveries with GET /webhooks/{id}/deliveries. After fixing your receiver, replay a failed delivery with POST /webhooks/{id}/deliveries/{delivery_id}/replay. The event ID stays the same.

Revoking the integration, losing account access, or ending the API/MCP add-on blocks outgoing delivery. Schedules already accepted by Crickets remain scheduled.