Webhooks

Form Events

Receive `FORM.SUBMISSION` events via webhook when a recipient completes a Pinnacle form. Fires once per successful submit — and again on every edit when the form was created with `can_update: true`. The payload includes the full form metadata, the submitter's answers (both keyed by `key` in `submission.data` and as a resolved `submission.fields` snapshot ready to render), and the conversation the form was sent in. `conversation` is only populated when the form was dispatched via `POST /forms/send` with a `to` recipient — it's null for URL-only sends and for forms whose URL was shared through any other channel (e.g. an RCS card built with `POST /send`). `sender` is hoisted to the event root so you can route on it without walking into the submission object. **Before trusting the payload, verify the `PINNACLE-SIGNING-SECRET` header matches the signing secret of the webhook this event was delivered to.** Respond with a `200` to acknowledge receipt — any non-2xx response causes Pinnacle to retry with exponential backoff.

Headers

PINNACLE-SIGNING-SECRETstringRequired
Secret for verifying the authenticity of the request. Starts with `pss-` and is unique for each webhook. Find it at [webhooks](https://app.pinnacle.sh/dashboard/development/webhooks).

Payload

The payload of this webhook request is an object.
typeenumRequired
Allowed values:
senderstringRequired

Top-level sender identifier — same value as submission.from. Exposed at the event root so you can route on it without digging into the submission object.

conversationobjectRequired

Conversation between the sender and the recipient the form was delivered to. Only populated when the form was dispatched via POST /forms/send with a to recipient — that’s the only call that opens a conversation tied to a form submission.

Null in every other case, including:

  • POST /forms/send without a to (URL-only mints — no message is sent, so no conversation exists).
  • Submissions to a form whose URL was shared by any other means (e.g. an RCS card built with POST /send, a chat message, a marketing email, or a link on your site). The recipient isn’t tied to a Pinnacle conversation in those flows.
formobjectRequired
Form summary carried on the FORM.SUBMISSION event.
submissionobjectRequired
The submitted answers plus a resolved snapshot of each form field.

Response

200
Return a 200 status to indicate that the data was received successfully