---
title: "Subscribe to signed events"
method: POST
path: "/webhooks"
tags: ["Webhooks"]
---

# Subscribe to signed events

`POST /webhooks`

## Request

- Base URL: `https://app.pumpgtm.com/api/v1`
- URL: `https://app.pumpgtm.com/api/v1/webhooks`
- Auth: HTTP bearer

Maximum 10 enabled hooks. Save the returned secret securely; it is shown only at creation. HTTPS port 443 and publicly resolving IPv4 DNS required. Private/mixed IPs, URL credentials, fragments and redirects are rejected. Registration is not idempotent: list before retrying after a timeout; 409 webhook_limit_reached at the maximum. Delivery is best-effort: up to three attempts, retried on network errors, 5xx and 429; not a durable replay queue. Verify signatures on the exact raw body (X-PumpGTM-Signature, t=<unix>,v1=<hex HMAC-SHA256 of t + "." + body>; reject t older than 5 minutes) and deduplicate event IDs. x.followed means an inbound follow of your connected account. lead.messaged includes successful x_dm with channel x; reply.received can include unreadable encrypted content. linkedin.connected fires on the partner workspace when an end user completes a hosted connect link; register it with the partner key. linkedin.disconnected fires when a connected LinkedIn identity stops being usable (source: provider, dashboard or api), on the owning workspace and, for a partner end user, on the partner workspace. linkedin.limited fires once when LinkedIn declines an account's connection requests and invites are held (data.account{id,displayName}, reason invite_limit, heldSince, retryAt = earliest automatic retry, attempt 1..3; a failed retry fires it again with the next attempt); linkedin.resumed fires when a retry goes through (data.account, resumedAt, warmupRestarted true: the account re-enters the six-day warm-up ramp). Messages and other steps keep running during a hold; nothing to do on your side.

## Headers

- `X-PumpGTM-Client` string, uuid
- `X-PumpGTM-User` string

## Request body

- object
  - `url` string, uri, required
  - `events` string[], required

## Response `201`

Successful response. Read outcome fields; success does not imply delivery.

- object
  - `id` string, uuid, required
  - `url` string, required
  - `events` string[], required
  - `secret` string, required

## Other responses

- `400`: Invalid input; for partner keys also user_header_required when the account requires X-PumpGTM-User
- `401`: Missing, invalid or revoked key
- `403`: Workspace mismatch, channel or feature disabled; for partner keys also enterprise_required and user_disabled
- `404`: Resource unavailable in this workspace
- `409`: Revision, identity or state conflict: { error, message } and nothing changed
- `429`: Rate limit; respect Retry-After when provided
- `500`: internal_error: an unexpected failure on our side; retry, then contact PumpGTM
- `503`: Dependency unavailable; identity may be unknown

## Changes

- **2026-10-12** `06d2e4d0e84b`: 8 info
  - the response property `error` became required for the status `400`
  - the response property `error` became required for the status `401`
  - the response property `error` became required for the status `403`
  - the response property `error` became required for the status `404`
  - …4 more
- **2026-10-12** `08c80059d483`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/pumpgtm/apis/pumpgtm-api/changes/webhooks/post.md)

---

[API](https://skmtc.dev/pumpgtm/apis/pumpgtm-api.md) - [All operations](https://skmtc.dev/pumpgtm/apis/pumpgtm-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pumpgtm/apis/pumpgtm-api/revisions/06d2e4d0e84b?raw)