Attach Webhook | Pinnacle

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.

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.

Authentication

PINNACLE-API-KEYstring

API Key authentication via header

Request

This endpoint expects an object.

senderslist of stringsRequired

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

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.

namestringOptional>=1 character

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

urlstringOptionalformat: "uri"

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

eventenum or nullOptional

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

USER.TYPING is only supported for RCS agent senders, not phone numbers.

Allowed values:

Response

Successfully attached webhook to the specified senders.

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

webhookobject

eventenum or null

The event type filter applied to these subscriptions.

Allowed values:

senderslist of strings

Senders that were successfully attached (phone numbers in E.164 format or RCS agent IDs).

failedlist of objects

Senders that could not be attached, with error details.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

500

Internal Server Error

1	import { PinnacleClient } from "rcs-js";
2
3	async function main() {
4	const client = new PinnacleClient({
5	apiKey: "YOUR_API_KEY_HERE",
6	});
7	await client.webhooks.attach({
8	senders: [
9	"+14155551234",
10	"agent_abc123",
11	],
12	});
13	}
14	main();

1	{
2	"webhook": {
3	"id": "wh_1234567890",
4	"name": "SMS Delivery Tracker",
5	"url": "https://api.myapp.com/webhooks/sms-delivery",
6	"secret": "pss_1a2b3c4d5e6f7g8h9i0j"
7	},
8	"event": "MESSAGE.STATUS",
9	"senders": [
10	"+14155551234",
11	"agent_abc123"
12	],
13	"failed": []
14	}