Skip to main content
POST
Create webhook endpoint

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
url
string
required

Public HTTPS URL to POST events to.

Required string length: 1 - 2048
events
enum<string>[]
required

Event types to send, at least one. See GET /v1/webhooks/event-types. To pause an endpoint, set enabled: false.

Required array length: 1 - 5 elements
Available options:
message.received,
inbox.suspended,
inbox.reactivated,
pod.suspended,
pod.reactivated
description
string | null

Your label for the endpoint.

Maximum string length: 500
secret
string

Optional. Leave empty and we generate a signing secret (returned once in this response). Paste a whsec_ key to get Standard Webhooks signatures. Paste any other token (or Bearer <token>) to have it sent as the Authorization header.

Maximum string length: 4096
inboxIds
string[]

Only send events for these inboxes.

Maximum array length: 500
podIds
string[]

Only send events for these pods and their inboxes.

Maximum array length: 500

Response

Endpoint created. secret is the full generated secret when auth is openmail.

Endpoint created. secret is the full generated secret when auth is openmail.

id
string

Webhook endpoint ID

url
string

HTTPS URL events are POSTed to.

description
string | null

Your label for the endpoint.

auth
enum<string>

How each request is authenticated, detected from the secret you set. openmail: we generated a secret and sign with HMAC-SHA256 (X-Signature, X-Timestamp). standard_webhooks: signed per the Standard Webhooks spec with your whsec_ key (webhook-id, webhook-timestamp, webhook-signature). bearer: your token is sent as Authorization: Bearer <token>.

Available options:
openmail,
standard_webhooks,
bearer
secret
string

Masked (****abcd) everywhere except the create, update, or rotate response that generated an OpenMail secret. A secret you supplied is never returned.

enabled
boolean

Disabled endpoints receive no events.

events
enum<string>[]

Subscribed event types.

Available options:
message.received,
inbox.suspended,
inbox.reactivated,
pod.suspended,
pod.reactivated
inboxIds
string[]

Limit events to these inboxes. With podIds also empty, the endpoint covers the whole organisation.

podIds
string[]

Limit events to these pods and every inbox in them.

createdAt
string<date-time>
updatedAt
string<date-time>
disabledAt
string<date-time> | null
stats24h
object

Delivery counts over the last 24 hours. Returned by list and get.