Webhooks

Webhooks deliver real-time HTTP notifications when events occur in your workspaces — a record is created, a comment is posted, a tag is removed, and more. When a subscribed event fires, Blue sends a signed POST request to your endpoint with the event type and the entity’s before/after state.

Webhooks are Webhook objects in the API, owned by the user who created them. Each webhook subscribes to a set of event types and is scoped to a set of workspaces (Project objects).

Operations

Authenticating webhook requests

Manage webhooks with your personal access token headers. createWebhook additionally requires X-Bloo-Company-ID because the webhook count is enforced per organization; the other webhook operations are user-scoped.

curl -X POST https://api.blue.cc/graphql \
  -H "Content-Type: application/json" \
  -H "X-Bloo-Token-ID: YOUR_TOKEN_ID" \
  -H "X-Bloo-Token-Secret: YOUR_TOKEN_SECRET" \
  -H "X-Bloo-Company-ID: YOUR_COMPANY_ID" \
  -d '{"query": "query { webhooks { items { id url status enabled } } }"}'

Delivery and scoping

Each event is enqueued with a 5-second delay before the first delivery attempt. Blue POSTs the payload to your URL with a 7-second request timeout.

A webhook only receives an event when all of the following hold:

• The webhook is enabled.
• Its events list contains the event type — or the list is empty, which subscribes it to every event.
• Its projectIds list contains the event’s workspace — or the list is empty, which scopes it to all workspaces.
• The webhook’s creator is currently a member of the event’s workspace. Project scoping is additionally gated by live membership, so removing the creator from a workspace silently stops delivery for events from it.

If a delivery attempt fails (non-2xx response, timeout, or connection error), BullMQ retries with backoff — 5 attempts by default. After all retries are exhausted, the webhook is automatically disabled (enabled: false, status: UNHEALTHY) and its creator is emailed. This is what HEALTHY versus UNHEALTHY reflects: a healthy webhook is delivering; an unhealthy one was auto-disabled (or disabled manually) and must be re-enabled via updateWebhook.

Webhook payload

Blue sends a JSON body with this exact shape:

{
  "event": "TODO_DONE_STATUS_UPDATED",
  "webhook": {
    "id": "clm4n8qwx000008l0g4oxdqn7",
    "uid": "wh_8f3a2c1e",
    "url": "https://example.com/webhooks/blue",
    "status": "HEALTHY",
    "enabled": true,
    "metadata": { "events": [], "projectIds": [] }
  },
  "previousValue": { "id": "todo_123", "title": "Draft proposal", "done": false },
  "currentValue": { "id": "todo_123", "title": "Draft proposal", "done": true }
}

The delivered event may also be WEBHOOK_HEALTH_CHECK, sent when a webhook is re-enabled to verify reachability. That value is not part of the WebhookEvent enum and cannot be subscribed to — it is delivery-only, so handle unknown event strings defensively.

Verifying signatures

Every delivery includes an X-Signature header: the HMAC-SHA256 of the raw request body, keyed by the webhook’s secret (the value returned once from createWebhook), encoded as a hex string.

const crypto = require('crypto')

// `rawBody` is the unparsed request body string (e.g. from a raw body parser).
function verifySignature(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader))
}

Webhook events

Subscribe to these WebhookEvent values via the events array on createWebhook or updateWebhook. An empty array subscribes to all of them.

Record events

Checklist events

List events

Custom field events

Tag events

Comment events

The Webhook type

WebhookStatusType is HEALTHY or UNHEALTHY.

Related

• Create a webhook
• List webhooks
• Update a webhook
• Disable a webhook
• Delete a webhook
• Authentication