Webhooks API

Overview

Webhooks allow you to receive real-time HTTP notifications when events occur in your Blue workspaces. When an event is triggered (such as a record being created or updated), Blue sends a POST request to your configured URL with details about the event.

Each webhook has a secret that is used to sign payloads with an HMAC SHA-256 signature, sent via the X-Signature header. The secret is only returned once at creation time and cannot be retrieved afterward.

Available Operations

Create a Webhook

The createWebhook mutation registers a new webhook endpoint that will receive event notifications.

Basic Example

mutation {
  createWebhook(input: {
    url: "https://example.com/webhooks/blue"
  }) {
    id
    uid
    url
    secret
    status
    enabled
    createdAt
  }
}

Advanced Example

mutation CreateWebhook($input: CreateWebhookInput!) {
  createWebhook(input: $input) {
    id
    uid
    name
    url
    secret
    status
    events
    projectIds
    enabled
    metadata
    createdAt
    updatedAt
  }
}

Variables:

{
  "input": {
    "name": "Slack Notifications",
    "url": "https://example.com/webhooks/blue",
    "events": [
      "TODO_CREATED",
      "TODO_DONE_STATUS_UPDATED",
      "COMMENT_CREATED"
    ],
    "projectIds": ["project-abc-123", "project-def-456"]
  }
}

Input Parameters

CreateWebhookInput

Response Fields

Available Webhook Events

Record Events

Checklist Events

List Events

Custom Field Events

Tag Events

Comment Events

Required Permissions

Webhooks are user-scoped. You can only create webhooks for workspaces you are a member of.

Error Responses

Invalid URL

{
  "errors": [{
    "message": "url is not valid",
    "extensions": {
      "code": "BAD_USER_INPUT"
    }
  }]
}

When: The provided url is not a valid URL format.

Private URL Rejected

{
  "errors": [{
    "message": "URL points to a private network",
    "extensions": {
      "code": "BAD_USER_INPUT"
    }
  }]
}

When: The provided url resolves to a private or internal network address.

Unauthorized Workspace Access

{
  "errors": [{
    "message": "Unauthorized",
    "extensions": {
      "code": "UNAUTHORIZED"
    }
  }]
}

When: One or more of the provided projectIds refer to workspaces you are not a member of.

Verifying Webhook Signatures

When Blue sends a webhook event, it includes an X-Signature header containing an HMAC SHA-256 hash of the request body, signed with your webhook’s secret. To verify:

const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');
  return hash === signature;
}

Important Notes

• Webhooks are user-scoped – each user manages their own webhooks independently.
• The secret is generated automatically and only returned once at creation time. Store it securely.
• If no events are specified, the webhook will not receive any notifications until events are configured via the updateWebhook mutation.
• If no projectIds are specified, the webhook applies across all workspaces you are a member of.
• URLs must be publicly accessible; private network addresses (localhost, 10.x.x.x, 192.168.x.x, etc.) are rejected.
• New webhooks are created in a HEALTHY status. The status changes to UNHEALTHY if delivery failures occur.