---
title: "Register webhook"
method: POST
path: "/v1/webhooks"
tags: ["Webhooks"]
---

# Register webhook

`POST /v1/webhooks`

## Request

- Base URL: `https://api.deadsimple.email`
- URL: `https://api.deadsimple.email/v1/webhooks`
- Auth: HTTP bearer

## Headers

- `X-Workspace-Id` string, uuid

## Request body

- object
  - `url` string, uri, required
  - `events` string[], required
  - `description` string
  - `headers` object: Optional custom headers sent on every delivery attempt and every retry — for endpoints that enforce their own auth (Bearer tokens, gateway keys). Values are write-only and are masked in every response. Reserved names (Content-Type, Host, User-Agent, hop-by-hop headers, and any `X-DSE-*` header) are rejected, as are values with control characters or non-ASCII bytes. Max 10 headers, 1024 characters per value.
  - `endpoint_secret` string: The receiving service's own Standard Webhooks secret (`whsec_...`), for endpoints that verify every request against it, such as Grok Automations. Each delivery then also carries `webhook-id` (the delivery id, stable across retries), `webhook-timestamp` and `webhook-signature` (`v1,<base64 HMAC-SHA256 of "id.timestamp.body">`) per standardwebhooks.com. Such receivers answer an unsigned request with HTTP 400. Write-only. A `whsec_` value supplied as `Authorization: Bearer whsec_...` in headers is treated the same way and not sent as a header.
  - `inbox_ids` string[]: Optional inbox scope. A webhook with inbox_ids fires only for events whose payload names one of those inboxes (so never for inbox-less events such as domain.verified). Every id must belong to the account. Omit or pass an empty list for an account-wide webhook. An inbox-scoped API key may only register webhooks for its own inboxes and gets them by default.

## Response `201`

Webhook created with signing secret (shown once)

---

[API](https://skmtc.dev/deadsimple/apis/dead-simple-email-api.md) · [All operations](https://skmtc.dev/deadsimple/apis/dead-simple-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/deadsimple/apis/dead-simple-email-api/revisions/c697881be131?raw)