---
title: "Create an outbound webhook subscription."
method: POST
path: "/webhook-subscriptions"
tags: ["webhooks"]
---

# Create an outbound webhook subscription.

`POST /webhook-subscriptions`

## Request

- Base URL: `https://api.coldrig.dev`
- URL: `https://api.coldrig.dev/webhook-subscriptions`
- Auth: HTTP bearer

Push reply, bounce, soft_bounce, complaint, and unsubscribe events to your own HTTPS endpoint instead of polling GET /activity. Deliveries are signed `X-Coldrig-Signature: sha256=HMAC-SHA256(secret, raw body)`. URLs must be https and resolve to a public host — private/link- local/metadata IPs are rejected, re-validated on every delivery.

## Request body

- WebhookCreateInput
  - `url` string, required: HTTPS endpoint that receives event POSTs. Must be https and resolve to a public host — private/link-local/metadata IPs are rejected.
  - `eventTypes` WebhookEventType[], required: Which event types to receive. At least one.
  - `secret` string: Optional HMAC signing secret (>=16 chars). Omit to have the server generate one, returned once on create.
  - `active` boolean: Whether the subscription delivers immediately. Defaults to true.

## Response `201`

Subscription created — the response carries the signing secret once.

- WebhookCreateResponse
  - `id` string, required
  - `url` string, required
  - `eventTypes` WebhookEventType[], required
  - `active` boolean, required
  - `status` 'active' | 'disabled', required
  - `disabledReason` string, nullable, required
  - `consecutiveFailures` integer, required
  - `createdAt` integer, required
  - `updatedAt` integer, required
  - `secret` string, required: HMAC signing secret — shown once on create, never returned on reads.

## Other responses

- `400`: Request body failed schema validation.
- `401`: Missing, invalid, or inactive bearer token.

---

[API](https://skmtc.dev/coldrig/apis/agent-cold-email-api.md) · [All operations](https://skmtc.dev/coldrig/apis/agent-cold-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/coldrig/apis/agent-cold-email-api/revisions/242a462d82c4?raw)