---
title: "Attach Webhook"
method: POST
path: "/webhooks/attach"
tags: ["Webhooks"]
---

# Attach Webhook

`POST /webhooks/attach`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/webhooks/attach`
- Auth: API key in header `PINNACLE-API-KEY`

Attach a webhook to one or more senders (phone numbers or RCS agent IDs) to receive real-time event notifications. <br>

You can attach an existing webhook by providing its ID, or create a new webhook by specifying a name and URL. Supports bulk operations with up to 50 senders per request. <br>

Subscriptions are additive — attaching new senders does not remove existing ones. Re-attaching the same sender updates the event type filter without creating duplicates. <br>

**Custom headers** may be provided in either case via the optional `headers` field. When attaching a new webhook, the headers are stored on the webhook and sent on every delivery. When attaching an existing `webhookId`, supplying `headers` **overwrites** the stored headers on that webhook — omit the field to leave them unchanged, or pass an empty object `{}` to clear them. The reserved `PINNACLE-SIGNING-SECRET` header is always set by Pinnacle and cannot be overridden.

## Request body

- AttachWebhookRequest: Attach a webhook to one or more senders. Provide either an existing `webhookId` or `name` + `url` to create a new webhook.
  - `senders` string[], required: Array of senders to attach the webhook to. Can be phone numbers in E.164 format or RCS agent IDs.
  - `webhookId` string: Existing webhook ID (starts with `wh_`). Provide this OR `name` + `url` to create a new webhook. The webhook must be in ENABLED status. Disabled webhooks can be re-enabled from the [dashboard](https://app.pinnacle.sh/dashboard/development/webhooks). Supplying `headers` alongside `webhookId` **overwrites** the stored headers on the webhook. Omit `headers` to leave them unchanged.
  - `name` string: Name for a new webhook (required if no `webhookId`).
  - `url` string, uri: HTTPS endpoint URL for a new webhook (required if no `webhookId`).
  - `event` 'MESSAGE.STATUS' | 'MESSAGE.RECEIVED' | 'USER.TYPING' | 'FORM.SUBMISSION' | 'CAMPAIGN.STATUS' | 'CALL.STATUS' | 'FAX.STATUS' | 'FAX.RECEIVED': Types of events that can trigger webhook notifications. Subscribe to specific events to receive real-time updates about your sender activity. Use `null` to listen to all events.
  - `headers` object, nullable: Optional custom HTTP headers (key-value map) to include when dispatching webhook events to the endpoint. Header names must start with a letter or digit and contain only letters, digits, `-`, or `_` (matching the pattern `^[A-Za-z0-9][A-Za-z0-9_-]*$`). Names are case-insensitive per [RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110#name-field-names) and are normalized to uppercase before storage and sending. When provided with an existing `webhookId`, these headers **overwrite** any headers currently stored on that webhook. Omit to leave existing headers unchanged. The reserved `PINNACLE-SIGNING-SECRET` header is silently ignored and cannot be overridden.

## Response `200`

Successfully attached webhook to the specified senders. <br>

Senders that could not be found are returned in the `failed` array with error details.

- AttachWebhookResponse
  - `webhook` AttachWebhookResponseWebhook, required
    - `id` string, required: Unique webhook identifier (starts with `wh_`).
    - `name` string, required: Name of the webhook.
    - `url` string, required: HTTPS endpoint URL where events are delivered.
    - `secret` string, required: Signing secret sent in the `PINNACLE-SIGNING-SECRET` header for request verification.
    - `headers` object, nullable: Optional custom HTTP headers sent on every webhook delivery. Header names must match the regex `^[A-Za-z0-9][A-Za-z0-9_-]*$` — start with a letter or digit and contain only letters, digits, `-`, or `_`. Keys are case-insensitive and stored in uppercase. Values must be strings. The reserved `PINNACLE-SIGNING-SECRET` header is never returned here and cannot be overridden.
  - `event` 'MESSAGE.STATUS' | 'MESSAGE.RECEIVED' | 'USER.TYPING' | 'FORM.SUBMISSION' | 'CAMPAIGN.STATUS' | 'CALL.STATUS' | 'FAX.STATUS' | 'FAX.RECEIVED', required: Types of events that can trigger webhook notifications. Subscribe to specific events to receive real-time updates about your sender activity. Use `null` to listen to all events.
  - `senders` string[], required: Senders that were successfully attached (phone numbers in E.164 format or RCS agent IDs).
  - `failed` FailedSender[], required: Senders that could not be attached, with error details.
    - `sender` string, required: The sender that failed.
    - `error` string, required: Reason for the failure.

## Other responses

- `400`: Validation failed. The payload has missing required fields and/or invalid types. <br> See https://zod.dev/error-formatting for more information.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `404`: The requested resource could not be found. <br> This may occur if the identifier is incorrect, the resource has been deleted, or you don't have permission to access it.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)