Webhooks
Gauge POSTs a signed JSON event to your HTTPS endpoint the moment something happens.
Instead of polling, give Gauge a URL. When something happens in your workspace (a ticket is
created, a chat is answered, a customer message arrives) Gauge sends a signed POST to
that URL within seconds, and keeps retrying if your server is down.
Set up an endpoint
- Open Developers → Webhooks in the console and choose Add endpoint.
- Enter an HTTPS URL on your server.
- Choose the events to subscribe to: an exact name (
support.ticket.created), a family (support.ticket.*), or*for every public event. - Copy the signing secret. It is shown once; Gauge stores it to sign, and you store it to verify.
- Choose Send test event and check that your endpoint answers
2xx.
You can pause an endpoint, change its URL or events, and rotate its secret at any time from the same screen.
Manage endpoints from code
The same endpoints, over the API (live keys only; a key pinned to an App manages only that App's endpoints):
| Endpoint | Scope | |
|---|---|---|
GET /v2/webhook-endpoints | webhooks:read | List endpoints |
POST /v2/webhook-endpoints | webhooks:write | Create one. The answer carries the signing secret, once |
GET /v2/webhook-endpoints/{id} | webhooks:read | One endpoint, with its last delivery and 24 h success rate |
PATCH /v2/webhook-endpoints/{id} | webhooks:write | Change url, events, connectionIds, projectId, apiVersion, enabled |
DELETE /v2/webhook-endpoints/{id} | webhooks:write | Delete it |
POST /v2/webhook-endpoints/{id}/rotate-secret | webhooks:write | New secret, once; overlapHours 24 (default) or 0 |
POST /v2/webhook-endpoints/{id}/test | webhooks:write | Send a signed sample of an event (default webhook.test) |
GET /v2/webhook-endpoints/{id}/deliveries | webhooks:read | Its delivery log |
GET /v2/events, GET /v2/events/{id} | events:read | The last 30 days of events, with the exact body delivered |
POST /v2/events/{id}/redeliver | webhooks:write | Send an event again |
curl https://app.gauge.chat/backend/v2/webhook-endpoints \
-H "Authorization: Bearer $GAUGE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: create-endpoint-orders" \
-d '{ "url": "https://example.com/gauge/webhooks", "events": ["message.received", "message.status_updated"] }'Subscribing to message or conversation events needs the key to also hold messages:read /
conversations:read, and contact events contacts:read; otherwise 403 insufficient_scope. An
endpoint created with a key belongs to the key's member and receives what that member can see.
New endpoints are created on the current API version (2026-10-21).
What a delivery looks like
POST /gauge/webhooks HTTP/1.1
Content-Type: application/json
Gauge-Signature: t=1792578071424,v1=5f2b8c0e9d4a7b1c3e6f8a2d4b9c7e1f0a3d5b8c2e4f6a9b1d3c5e7f9a2b4c6d
Gauge-Event-Id: 48213907
Gauge-Event-Type: support.ticket.created
Gauge-Delivery-Attempt: 1
Gauge-Webhook-Id: 4c2a6e8f-0b1d-4f3a-9c5e-7a9b1d3f5a7c
x-pulse-event: support.ticket.created
x-pulse-timestamp: 1792578071424
x-pulse-signature: sha256=5f2b8c0e9d4a7b1c3e6f8a2d4b9c7e1f0a3d5b8c2e4f6a9b1d3c5e7f9a2b4c6d{
"id": "48213907",
"event": "support.ticket.created",
"livemode": true,
"workspaceId": "a3b5c7d9-1e2f-4a6b-8c0d-2e4f6a8b0c1d",
"entity": "support_ticket",
"entityId": "5e7c9a1b-3d5f-4b7d-9f1a-3c5e7a9b1d3f",
"occurredAt": "2026-10-21T09:41:11.424Z",
"payload": { "…": "the event's own fields, see the catalogue" }
}| Field | |
|---|---|
id | The event id: evt_… for message, conversation and contact events, a number for support events. The same on every retry and every manual resend. Deduplicate on it. |
event | The event name, also in the Gauge-Event-Type header. |
livemode | false when the event is about sandbox data (a test App), else true. |
workspaceId | Your workspace. |
entity, entityId | What the event is about. |
occurredAt | When it happened (ISO 8601, UTC). |
payload | The event's fields, defined per event in the catalogue. |
Payloads carry ids and the facts of the event, never secrets or internal routing data. Fetch the full resource from the API when you need more.