Webhooks

Webhooks Overview

Webhooks let trumpet notify your own endpoint in near real-time when engagement happens inside a Pod — a viewer opens it, asks a question, plays a video, downloads a file, and so on. Instead of polling, you register an HTTPS endpoint and trumpet POSTs a signed JSON payload to it as events occur.

How webhooks work

Create an endpoint

In Settings → Webhooks in the trumpet dashboard, click Add Endpoint, enter a publicly reachable HTTPS URL, optionally name it, and select which events it should receive. Webhooks are managed in the dashboard, not via the API.

Save your signing secret

When you create an endpoint, trumpet generates a signing secret prefixed with whsec_.

🔒

Copy your signing secret now

Your signing secret is shown only once at creation (and again only if you regenerate it). It cannot be retrieved later. Store it in a secrets manager or environment variable immediately.

Receive events

trumpet sends an HTTP POST to your URL with a JSON body and a Trumpet-Signature header. Respond promptly with a 2xx status to acknowledge receipt.

Verify every request

Before trusting a payload, verify the Trumpet-Signature header using your signing secret. See Verifying Signatures for the full process and code samples.

Requirements & behaviour

Endpoint URLs must use https://. Plain http:// is rejected.

Endpoints must resolve to a public address. URLs pointing to localhost, .local hosts, or private, internal, or link-local IP ranges are rejected both when saving and at delivery time. Do not point webhooks at internal services.

Delivery is fire-and-forget with no automatic retries in this version. If your endpoint is down or returns a non-2xx status, that delivery is recorded as failed and is not retried.

💡

Design for best-effort delivery

Return 2xx quickly and do any heavy processing asynchronously on your side. Treat webhooks as best-effort and reconcile critical state by other means (e.g. periodic API polling) if needed. Slow endpoints will be recorded as failed even if they would eventually have responded — trumpet enforces a short delivery timeout of a few seconds.

Delivery logs: the dashboard shows recent delivery attempts per endpoint — event type, response status, response time, and any error — so you can debug failures yourself.

Endpoint statuses

Status	Meaning
`Active`	Deliveries are being sent normally.
`Paused`	You paused the endpoint. No deliveries are sent until you resume it.
`Disabled`	trumpet has disabled the endpoint (e.g. due to repeated failures). Contact support to re-enable.

The payload

Every event delivery shares the same envelope structure:

Example payload

{
  "id": "69f0bafc4cc54b506b0355d8",
  "event": "event.pod_is_viewed",
  "created": 1717160000,
  "api_version": "1",
  "data": {
    "type": "event.pod_is_viewed",
    "pod": "69f0bafc4cc54b506b0355d8",
    "crm": {
      "id": "123",
      "type": "salesforce",
      "object": "Opportunity",
    },
    "content": "Human-readable description of what happened",
    "context": { "...": "event-specific context" },
    "viewer": "viewer@example.com"
  }
}

Field	Type	Description
`id`	string	Unique identifier for this event. Use it as an idempotency key: the same event may in principle be delivered more than once, so dedupe on id and ignore repeats.
`event`	string	The event type, e.g. event.pod_is_viewed. See the Event Reference.
`created`	number	Unix timestamp (seconds) when the event was generated.
`api_version`	string	Payload schema version. Currently "1".
`data`	object	Event details (see below).
`data.type`	string	Same as the top-level event.
`data.pod`	string	The ID of the Pod the event relates to.
`data.crm`	object	CRM details if the Pod is linked to a CRM record (shape varies by CRM).
`data.crm.id`	string	CRM record ID, where applicable.
`data.crm.type`	string	CRM type, e.g. salesforce, hubspot, etc., where applicable.
`data.crm.object`	string	CRM object type, e.g. Opportunity, Contact, deals, companies, etc., where applicable.
`data.content`	string	A human-readable summary of the event.
`data.context`	object	Event-specific context (shape varies by event type).
`data.viewer`	string	Email of the viewer associated with the event, where available.

⚠️

Personal data in payloads

Payloads can contain personal data such as a viewer's email address. Endpoints receive data about engagement with the customer's own Pods. You are responsible for handling this data in line with your own data-protection obligations.

Headers sent with each delivery

Header	Value
`Content-Type`	application/json
`Trumpet-Signature`	Signature used to verify authenticity (see Verifying Signatures).
`User-Agent`	Trumpet-Webhooks/1.0