Receiving Messages and User Events

Setting up webhooks

To receive inbound messages and status updates, configure a webhook in the Pinnacle Dashboard:

Custom request headers

You can configure additional HTTP headers that Pinnacle includes on every webhook delivery — for example, a static API key, an internal routing token, or a tracing identifier. Set them in the dashboard when creating or editing a webhook, or pass an optional headers map to POST /webhooks/attach. Headers can be supplied whether you’re creating a new webhook or attaching an existing one by ID:

1
// Creating a new webhook
2
{
3
  "name": "Orders webhook",
4
  "url": "https://example.com/webhook",
5
  "headers": {
6
    "X-API-KEY": "sk_live_...",
7
    "X-TENANT-ID": "tenant_42"
8
  },
9
  "senders": ["+14155551234"]
10
}

1
// Attaching an existing webhook — headers overwrite what's stored
2
{
3
  "webhookId": "wh_1234567890",
4
  "headers": {
5
    "X-API-KEY": "sk_live_rotated_...",
6
    "X-TENANT-ID": "tenant_42"
7
  },
8
  "senders": ["+14155551234"]
9
}

Header rules:

• Names must match the pattern ^[A-Za-z0-9][A-Za-z0-9_-]*$ — start with a letter or digit, then letters, digits, -, or _.
• Names are case-insensitive per RFC 9110 and normalized to uppercase before storage and sending.
• Values must be strings.
• The PINNACLE-SIGNING-SECRET header is reserved for signature verification — any attempt to set it is silently stripped.

Overwrite semantics when using webhookId:

• Supplying headers replaces the entire stored header map on that webhook.
• Omitting headers leaves the stored headers unchanged.
• Passing an empty object {} clears all custom headers from the webhook.

Processing webhook events

Pinnacle SDKs provide a process() method to securely handle incoming webhook requests:

• Verifies webhook signatures by comparing your signing secret with the PINNACLE-SIGNING-SECRET in the headers.
• Parses and validates the request payload.
• Returns fully typed MessageEvent or UserEvent objects.

Event types

For full code examples in TypeScript, Python, and Ruby, see the SMS quickstart and RCS quickstart receive guides.

Form submissions

When a recipient fills out a form delivered via POST /forms/send, a FORM.SUBMISSION event is delivered to every webhook subscribed to the sender. The payload differs from message events — there is no message or status field; instead the event carries a resolved snapshot of the form definition paired with the submitted values so you can render or route on the response without an extra get_form call.

Payload shape:

1
{
2
  "type": "FORM.SUBMISSION",
3
  "sender": "agent_iM9wQcyBBjYn",
4
  "conversation": {
5
    "id": "convo_H2tiG5kvhxQQHUb6",
6
    "from": "agent_iM9wQcyBBjYn",
7
    "to": "+14155551234"
8
  },
9
  "form": {
10
    "id": "form_abc123",
11
    "url": "https://forms.pinnacle.sh/form_abc123",
12
    "name": "Contact request"
13
  },
14
  "submission": {
15
    "id": "fsub_xyz789",
16
    "from": "agent_iM9wQcyBBjYn",
17
    "to": "+14155551234",
18
    "data": {
19
      "full_name": "Ada Lovelace",
20
      "email": "ada@example.com",
21
      "plan": "pro",
22
      "interests": ["rcs", "sms"]
23
    },
24
    "fields": [
25
      { "key": "full_name", "label": "Full name", "type": "text", "value": "Ada Lovelace" },
26
      { "key": "email", "label": "Email", "type": "email", "value": "ada@example.com" },
27
      { "key": "plan", "label": "Plan", "type": "select", "value": "pro" },
28
      { "key": "interests", "label": "Interests", "type": "checkbox", "value": ["rcs", "sms"] }
29
    ],
30
    "ip_address": "203.0.113.45",
31
    "user_agent": "Mozilla/5.0 …",
32
    "submitted_at": "2026-04-24T00:35:04.406+00:00"
33
  }
34
}

Notes:

• sender at the event root is convenience-duplicated from submission.from so you can route on it without unwrapping.
• conversation is null when the form was minted URL-only (no to at send time). In that case submission.to is also null.
• For can_update=true forms, each edit fires a fresh FORM.SUBMISSION event with the updated values.
• Every field from the form definition is included in submission.fields, even those the recipient left blank — check value for null or an empty array.

RCS Fallback Messages

When you send an RCS message with a fallback configured and the RCS message cannot be delivered (e.g., the recipient’s device doesn’t support RCS), the system will automatically send the fallback SMS/MMS message instead.

Webhook routing

Fallback events are delivered to two different webhooks:

1. RCS agent’s webhook receives a MESSAGE.STATUS event with:

   • status: FALLBACK_SENT
   • fallbackMessage: Details of the SMS/MMS message that was sent instead, including its message ID, type, sender, recipient, text, and any media URLs.

2. Fallback phone number’s webhook receives MESSAGE.STATUS events related to the fallback message that was sent.