Attach Webhook API Reference

Serverhttps://api.pinnacle.sh/

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

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.

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

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.

Authorization

Pinnacle API key

PINNACLE-API-KEY<token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Attach a webhook to one or more senders. Provide either an existing webhookId or name + url to create a new webhook.

sendersarray<string>

Array of senders to attach the webhook to. Can be phone numbers in E.164 format or RCS agent IDs.

Items

1 <= items <= 50

Each item

Example

"+14155550100"

webhookIdstringOptional

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.

Supplying headers alongside webhookId overwrites the stored headers on the webhook. Omit headers to leave them unchanged.

Example

"webhook_01J8K3R7M9"

namestringOptional

Name for a new webhook (required if no webhookId).

Length

1 <= length

Example

"Acme Support"

urlstringOptional

HTTPS endpoint URL for a new webhook (required if no webhookId).

Format

uri

Example

"https://example.com/webhooks/pinnacle"

2 variantsOptional

Event type filter for the subscription. Set to null to receive all events.

USER.TYPING and CAMPAIGN.STATUS are only supported for RCS agent senders, not phone numbers — attempting to attach either of these events to a phone number returns 400 Bad Request.

Default

null

objectOptional

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 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 Body

`application/json`

Pinnacle client libraries

import { PinnacleClient } from "rcs-js";

const client = new PinnacleClient({
  apiKey: process.env.PINNACLE_API_KEY!,
});

await client.webhooks.attach({
    senders: ["+14155551234", "agent_abc123"]
});

Responses

{  "webhook": {    "id": "wh_1234567890",    "name": "SMS Delivery Tracker",    "url": "https://api.myapp.com/webhooks/sms-delivery",    "secret": "pss_1a2b3c4d5e6f7g8h9i0j",    "headers": {      "X-API-KEY": "sk_live_...",      "X-TENANT-ID": "tenant_42"    }  },  "event": "MESSAGE.STATUS",  "senders": [    "+14155551234",    "agent_abc123"  ],  "failed": []}

Attach Webhook

Request body

Authorization

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Try asking

Attach Webhook

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

400application/json

401application/json

404application/json

500application/json

Authorization

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`