Webhooks

Create a webhook

Register a webhook endpoint to receive event notifications. Maximum 10 webhooks per account. The secret is only returned at creation time. Pass mailbox_ids or domain_ids to receive mailbox and domain events for only those resources; unknown IDs are rejected with a 422 whose details code is invalid_mailbox_ids or invalid_domain_ids. Pass authorization to send that value as the Authorization header of every delivery; it is write-only. Pass standard_webhooks_secret to sign every delivery the way Standard Webhooks receivers check; it is write-only too.

post/webhooks

Request

  • Base URL: https://shipmail.to/api/v1
  • URL: https://shipmail.to/api/v1/webhooks
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://shipmail.to/api/auth/oauth2/authorize, token URL https://shipmail.to/api/auth/oauth2/token)

Headers

X-Shipmail-Organizationstring

OAuth access tokens only. The organization ID this request acts on. Required when the OAuth connection was approved for several organizations (400 validation_error without it); optional with one. An organization the connection was not approved for returns 403 authorization_error. Ignored for API keys, which belong to one organization.

Request body

urlstring uri required

HTTPS endpoint URL.

eventsWebhookEventType[] required

Event types to subscribe to.

descriptionstring

Human-readable description.

mailbox_idsstring[] nullable

Only deliver events for these mailboxes (plus mailboxes of domain_ids). Omit or null for every mailbox. Organization events are always delivered.

domain_idsstring[] nullable

Only deliver events for these domains and their mailboxes. Omit or null for every domain.

authorizationstring nullable

Sent verbatim as the Authorization header of every delivery to this webhook, including test events and replays. For example Bearer <key>. Printable ASCII only. Stored encrypted and never returned; responses carry has_authorization instead. Signature headers are sent as usual.

standard_webhooks_secretstring nullable

A Standard Webhooks signing secret from the receiving service, such as a Grok automation webhook trigger: whsec_ followed by a 24 to 64 byte key in standard base64 (with or without padding) or base64url. When set, every delivery, test event and replay also carries webhook-id (the event id, the same on every retry and replay), webhook-timestamp and webhook-signature. Stored encrypted and never returned; responses carry has_standard_webhooks_secret instead. The X-Shipmail-Signature headers are sent as usual.

include_reply_textboolean

Add reply_text, the sender's new text without quoted history or signature, to message.received deliveries. Turning it on needs an API key that also grants messages:read. Otherwise the request fails with 403. The same check applies to a URL, event, mailbox or domain change on a webhook that includes it.

authenticated_senders_onlyboolean

Deliver message.received only when the sender is authenticated (sender_authenticated: true): the sender passed DMARC, or Shipmail's own record shows a Shipmail mailbox sent the message. Other events are unaffected. Use it for agents that act on mail and must not trust a forged From address.

allowed_sendersstring[] nullable

Deliver message.received only when data.from.address equals an address entry (jane@customer.com) or its domain equals a domain entry (customer.com) exactly. Subdomains do not match, and a message without a From address never matches. Entries are trimmed, lowercased and deduplicated. Null or [] delivers every sender. Combines with authenticated_senders_only; other events are unaffected.

Response

Webhook created. The secret field is only included in this response.

object'webhook' required
idstring required
urlstring uri required
eventsWebhookEventType[] required
activeboolean required
descriptionstring nullable required
mailbox_idsstring[] nullable required

Mailboxes this webhook is limited to, or null. See Scoping in the webhooks guide.

domain_idsstring[] nullable required

Domains this webhook is limited to, or null. When both lists are null the webhook receives events for every mailbox.

has_authorizationboolean required

True when deliveries carry an Authorization header set through authorization. The value itself is never returned.

has_standard_webhooks_secretboolean required

True when deliveries carry Standard Webhooks signatures (webhook-id, webhook-timestamp, webhook-signature) from a secret set through standard_webhooks_secret. The secret itself is never returned.

include_reply_textboolean required

True when message.received deliveries carry reply_text.

authenticated_senders_onlyboolean required

True when message.received is delivered only for messages whose sender is authenticated (sender_authenticated: true): the sender passed DMARC, or Shipmail's own record shows a Shipmail mailbox sent the message.

allowed_sendersstring[] nullable required

Addresses and domains message.received is limited to, lowercased. Null when every sender is delivered.

created_atstring date-time required
updated_atstring date-time required
secretstring required

HMAC signing secret. Only returned at creation time.

Changes

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