Webhooks

Create a webhook endpoint

Requires scope: manage. Registers an HTTPS endpoint to receive events. The signing_secret is returned ONCE — use it to verify signatures. An empty event_types list is refused with 422 invalid_param_value: an endpoint with no event types would never be sent anything. Closed to apps connected by sign-in (403 connected_app_not_allowed): use the dashboard, an API key or the mails CLI.

post/v1/webhooks

Request

  • Base URL: https://api.mails.ai
  • URL: https://api.mails.ai/v1/webhooks
  • Auth: HTTP bearer

Request body

urlstring uri required

The https:// URL events are POSTed to. Its host must resolve to public IP addresses only. A host that does not resolve, or resolves to a private, loopback or link-local address, is refused with 400 invalid_param_value.

event_typesstring[]

Events to deliver, at least one. "*" is every event except thread.created, thread.updated, thread.deleted and message.delayed, sent only to an endpoint that names them.

descriptionstring

A note of your own to tell endpoints apart, up to 255 characters. Left out, description is null.

Response

The created endpoint, including the one-time signing secret.

idstring required

Webhook endpoint id (whe_…).

urlstring uri required

The URL events are POSTed to, as you sent it.

signing_secretstring required

HMAC secret for verifying webhook signatures. SHOWN ONCE.

event_typesstring[] required

The event types this endpoint receives: what you sent, or * alone when you left it out.

descriptionstring nullable

Your note about the endpoint; null when you sent none.

activeboolean required

Always true: a new endpoint starts active. Pause it with active: false on PATCH /v1/webhooks/{id}.

created_atstring required

When the endpoint was created (ISO 8601, UTC).

Changes

No recorded changes to this operation across all 1 revision of this API.