---
title: "Update a webhook endpoint"
method: PATCH
path: "/v1/webhooks/{webhook_id}"
tags: ["webhooks"]
---

# Update a webhook endpoint

`PATCH /v1/webhooks/{webhook_id}`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/webhooks/{webhook_id}`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Updates the webhook endpoint. Only the fields you send change: `events` replaces the
whole subscription set, and `status` pauses or re-enables delivery.

The `200` response is the updated endpoint. Invalid input (a non-HTTPS or non-public
`url`, an event type outside the catalog) returns a `422`.

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Request body

- WebhookEndpointUpdate
  - `url` string, uri: Replacement delivery URL. Same rules as at creation: HTTPS, at most 2048 characters, and the host must be publicly reachable (private, loopback, and link-local addresses return a `422`). Omit to keep the current URL. A connector endpoint's URL comes from its connector and cannot be replaced: any value returns a `422`.
  - `description` string: Human-readable label for this endpoint, up to 256 characters.
  - `filter` WebhookFilter: Exact match on `mailbox_id`, for `email_mailbox.*` events only; the mailbox must belong to this workspace. Cannot be combined with Realtime app scope. Omit on create for all resources; on update omit to keep, send `null` to clear.
    - `mailbox_id` string, required
  - `events` WebhookEventType[]: Replaces all event subscriptions with this list. Omit to keep the current set. Types outside the event catalog return a `422`.
  - `destination` WebhookDestinationUpdate: Changes to how deliveries are built, shaped as at creation. Only a `connector` destination takes `connector`; on any other endpoint it returns a `422`. Omit to keep the destination.
    - `type` 'webhook' | 'connector': How deliveries to the webhook endpoint are built: `webhook` posts the signed event unchanged to the endpoint URL; `connector` builds the delivery using the configured connector action. An existing endpoint's type cannot change; a different value returns a `422`.
    - `connector` WebhookConnectorSetupUpdate: Changes to the endpoint's connector, nested as on creation. A field the endpoint's URL is built from moves the URL with it. New deliveries are prepared with the current config. Queued deliveries keep their prepared body, but every send attempt, including retries, uses the current destination URL and credentials.
      - `connector_id` string: The connector to deliver through. Each connector, its fields and the setup to do on its platform first: - `claude_managed_agents`: Claude Managed Agents. Send each message you receive to your Claude managed agent. - `agent_id` (`config`, required): Returned when you create the agent. Sessions use its latest version. - `environment_id` (`config`, required): Returned when you create the environment. - `vault_id` (`config`, optional): A credential vault the agent uses, such as the one holding its Bird MCP credential, so it can reply through Bird. - `api_key` (secret, in `credentials`, required): From the Claude workspace your agent runs in. - Events: `whatsapp.received`, `sms.received`, `email_mailbox.message_received`, `amb.received`. - Setup 1: First, set up your agent in Claude. In the Claude Console, create the agent, its environment and an API key in the same workspace, then come back here with their IDs and the key. See https://platform.claude.com/docs/en/managed-agents/quickstart#create-your-first-session. - Setup 2: Create an API key. In the Claude workspace your agent runs in. See https://platform.claude.com/settings/keys. - Setup 3: Copy the agent and environment IDs. Each create returns its ID. See https://platform.claude.com/docs/en/managed-agents/quickstart#create-your-first-session. - Setup 4: Optionally, add a credential vault. To let the agent reply through Bird, store its Bird MCP credential in a Claude credential vault and give the vault ID here. Each session gets that vault. See https://platform.claude.com/docs/en/managed-agents/vaults. - `grok_bot`: Grok Bot. Send each message you receive to a Grok Bot routine. - `webhook_url` (`config`, required): The routine's webhook URL. - `sender_key` (secret, in `credentials`, required): The routine's sender key. Bird sends it only as the Bearer token. - Events: `whatsapp.received`, `sms.received`, `email_mailbox.message_received`, `amb.received`. - Setup 1: First, ask Grok Bot to create a routine. Ask Grok Bot to create a routine with a webhook trigger, then paste the webhook URL and sender key it gives you below. See https://cursor.com/docs/cloud-agent/automations#webhook-triggers.
      - `action` string: Identifier of an action, unique within its connector.
      - `credentials` ConnectionCredentials: Values for the connector's secret fields, keyed by field `name`. Every required secret field must be present, after merging with the stored values on an update, and a key the connector does not declare as secret returns a `422`. No response includes these values.
      - `config` ConnectionConfigPatch: Changes to the connector's nonsecret fields, keyed by field `name`. A key given replaces that field, `null` clears an optional one, and a key left out keeps its stored value. A required field cannot be cleared, and the result is checked as at creation.
  - `status` 'active' | 'paused': `paused` stops all deliveries; `active` re-enables a paused endpoint. Omit to leave the status unchanged. Events that fire while paused are not delivered and a replay cannot recover them, because they were never attempted; after re-enabling, [Replay failed deliveries](/docs/api/reference/create-webhook-replay) reaches only the deliveries that failed before the pause. A `degraded` endpoint cannot be reset through this field: it returns to `active` automatically once deliveries succeed again.

## Response `200`

Webhook endpoint after the update.

- WebhookEndpoint
  - `id` string, required
  - `url` string, uri, required: HTTPS URL where the API delivers events for this endpoint.
  - `description` string: Human-readable label for the endpoint.
  - `filter` WebhookFilter, required: Exact match on `mailbox_id`, for `email_mailbox.*` events only; the mailbox must belong to this workspace. Cannot be combined with Realtime app scope. Omit on create for all resources; on update omit to keep, send `null` to clear.
    - `mailbox_id` string, required
  - `events` WebhookEventType[], required: Event types this endpoint is subscribed to; only matching events are delivered. Change the set with [Update a webhook endpoint](/docs/api/reference/update-webhook).
  - `status` 'active' | 'degraded' | 'paused', required: Delivery state of the endpoint. - `active`: The initial state; events are being delivered normally. - `degraded`: Recent deliveries are failing. We keep delivering and retrying, and the endpoint returns to `active` automatically once deliveries succeed again. - `paused`: All delivery is stopped, either because an update set `status` to `paused` or automatically after sustained delivery failures. A paused endpoint never resumes on its own: re-enable it with [Update a webhook endpoint](/docs/api/reference/update-webhook), then [Replay failed deliveries](/docs/api/reference/create-webhook-replay) to recover the deliveries that failed before the pause. Events that arrived while it was paused were never attempted, so a replay does not reach them.
  - `destination` union: How each delivery to the endpoint is built. The type cannot change after the endpoint is created.
    - WebhookRawDestination: Posts the signed event to the endpoint's `url` unchanged.
      - `type` 'webhook', required
    - WebhookConnectorDestination: Sends the request a connector action builds, with the credentials stored for this endpoint. The endpoint's URL comes from its connector setup, so updating the endpoint with a `url` returns a `422`.
      - `type` 'connector', required
      - `connector` WebhookConnectorBinding, required
        - `connector_id` string, required: Stable identifier of a connector, such as `claude_managed_agents`.
        - `action` string, required: Identifier of an action, unique within its connector.
        - `connection_name` string, required: Label of the credentials the endpoint delivers with.
        - `config` ConnectionConfig: Values for the connector's nonsecret fields, keyed by field `name`, such as the URL the endpoint's requests go to. A URL must be HTTPS, on one of the connector's `allowed_origins`, and under its `path_prefix` when it has one. It cannot include user info, a fragment, an IP address as its host, dot segments, or encoded slashes.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/3e2a50466454?raw)