Update a Webhook

Use the updateWebhook mutation to change an existing webhook’s URL, name, subscribed events, workspace scope, or enabled status. Every field except webhookId is optional, so you can patch a single attribute or several at once. Only the user who created a webhook can update it.

Webhooks are scoped to an organization (an Organization in the API) and the request runs with your personal access token headers. Re-enabling a webhook (enabled: true) triggers a live health check before the change is committed — see Health check below.

Request

This example renames a webhook and points it at a new endpoint:

mutation UpdateWebhook {
  updateWebhook(
    input: {
      webhookId: "clm4n8qwx000008l0g4oxdqn7"
      name: "Production notifications"
      url: "https://example.com/webhooks/blue"
    }
  ) {
    id
    name
    url
    status
    enabled
    updatedAt
  }
}

Send your credentials as headers (header names are case-insensitive):

POST https://api.blue.app/graphql
blue-token-id: YOUR_TOKEN_ID
blue-token-secret: YOUR_TOKEN_SECRET
blue-org-id: YOUR_ORG_ID
Content-Type: application/json

Parameters

UpdateWebhookInput

An empty events list (or omitting it on create) subscribes the webhook to all event types. The full set of WebhookEvent values is documented on the Webhooks overview.

Response

updateWebhook returns the updated Webhook object (Webhook!, non-null).

{
  "data": {
    "updateWebhook": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "name": "Production notifications",
      "url": "https://example.com/webhooks/blue",
      "status": "HEALTHY",
      "enabled": true,
      "updatedAt": "2026-05-29T14:22:08.000Z"
    }
  }
}

Returns — Webhook

Full example

Replace the subscribed events and workspace scope, and re-enable the webhook, using variables:

mutation UpdateWebhook($input: UpdateWebhookInput!) {
  updateWebhook(input: $input) {
    id
    uid
    name
    url
    status
    events
    projectIds
    enabled
    updatedAt
  }
}

{
  "input": {
    "webhookId": "clm4n8qwx000008l0g4oxdqn7",
    "events": [
      "TODO_CREATED",
      "TODO_DELETED",
      "TODO_DONE_STATUS_UPDATED",
      "TODO_ASSIGNEE_ADDED",
      "TODO_ASSIGNEE_REMOVED",
      "COMMENT_CREATED"
    ],
    "projectIds": ["project_123"],
    "enabled": true
  }
}

Health check

When the request sets enabled: true, Blue verifies the endpoint is reachable before committing the change. The check runs against the effective URL — the new url if you supplied one in the same call, otherwise the webhook’s current URL. So updating url and enabled: true together validates the new endpoint.

The check is a POST to the effective URL with this body:

{
  "event": "WEBHOOK_HEALTH_CHECK",
  "webhook": { "...": "the webhook object", "secret": "" }
}

• The secret field in the body is blanked to "", but the request is still signed with the webhook’s real secret via an HMAC-SHA256 X-Signature header — verify the signature with your stored secret.
• The health-check body has no previousValue / currentValue keys; it differs from real event deliveries by design. Use the event value to distinguish a probe from a real delivery.
• The request has a 7-second timeout. Any 2xx response passes.

If the check passes, the webhook is enabled and status becomes HEALTHY. If it times out or returns a non-2xx status, the update still succeeds but the webhook is left disabled with status set to UNHEALTHY. Setting enabled: true always runs the check, even if the webhook was already enabled.

Errors

Permissions

You can only update a webhook you created (createdById must match the authenticated user). There is no organization-level override — even an organization owner cannot update another user’s webhook through this mutation.

Note that disableWebhook does not apply this ownership check: any authenticated user with access can disable a webhook by ID. To disable a webhook you own, either send enabled: false here or use disableWebhook.

Related

• List webhooks
• Delete a webhook
• Webhooks overview — create a webhook, the event catalog, and signature verification