webhooks · MachineMail Docs

webhooks create

Webhook endpoints, deliveries and replay. Also spelled webhook.

Command	Summary
`webhooks create`	Create webhook
`webhooks delete`	Delete webhook
`webhooks deliveries`	List deliveries
`webhooks get`	Get webhook
`webhooks headers`	Get webhook headers
`webhooks list`	List webhooks
`webhooks replay`	Replay delivery
`webhooks test`	Send test event
`webhooks update`	Update webhook
`webhooks update-headers`	Update webhook headers

Every command also takes the global flags.

`webhooks create`

Create webhook.

The response includes secret (whsec_…), the key of the X-MachineMail-Signature HMAC. See the webhooks section of this document for the request MachineMail sends for each event type.

Under /v0/pods/{pod_id} or /v0/inboxes/{inbox_id}, or with a pod- or inbox-scoped credential, the webhook belongs to that pod or inbox (—pod, —inbox) and never receives events outside it.

A webhook delivers no event its creator could not read: each listed event type needs its read permission (message.* needs message_read, inbox.* inbox_read, domain.* domain_read, draft.* draft_read, webhook.test webhook_read), else 403. An empty —event-types from a credential without all of them is stored as the types it may read (403 when there are none).

Custom request headers in —headers are sent with every delivery (for example Authorization: Bearer for an endpoint that requires it). Their values are write-only: responses list only header_names.

Requires the webhook_create permission.

machinemail webhooks create [flags]

`Flags`

Field	Description
`--inbox <inbox-id>`	Create it in this inbox.
`--pod <pod-id>`	Create it in this pod.
`--url <url>`	Endpoint URL: a public http(s) URL (private and loopback addresses are rejected, and re-checked before every delivery).
`-e, --event-types`	Event types the webhook receives. Omit it or send an empty array to receive every event type except domain.updated and trusted_domain.*, which are sent only when listed. Repeat the flag for several values.
`--client-id <id>`	Idempotency key: a create with a --client-id already used in the organization returns that webhook with 200, or 409 when that webhook is outside the pod or inbox of the API key or route.
`--headers <json>`	Custom HTTP headers sent with every delivery to this webhook (every attempt, retry, replay and test event), alongside the X-MachineMail-* headers, for example {"Authorization": "Bearer "} for an endpoint that requires one. Values are write-only: they are stored encrypted and no response returns them; reads list the names (header_names). The headers are not part of the signed payload: X-MachineMail-Signature covers the body only. At most 10 headers. Names are HTTP tokens of up to 64 characters, compared without regard to case; values are printable ASCII (no line breaks or control characters) of up to 4096 characters, with surrounding spaces removed, and names plus values total at most 8192 bytes. Reserved names are refused with 400: Host, Content-Length, Content-Type, Content-Encoding, Transfer-Encoding, Connection, Upgrade, TE, Trailer, Keep-Alive, Expect, User-Agent, Accept-Encoding, and every name starting with Proxy-, Sec-, X-MachineMail-, Svix- or Webhook-. Authorization and Cookie are allowed.
`--header <"Name: value">`	Custom delivery header "Name: value" (repeatable), for example "Authorization: env:TOKEN". Value - reads stdin, env:VAR reads an environment variable (keeps secrets out of shell history). Repeat the flag for several values.
`-d, --data <json	@file

`Examples`

machinemail webhooks create --url https://example.com/hooks/machinemail -e message.received -e message.bounced
machinemail webhooks create --url https://example.com/hooks/machinemail --inbox agent@machinemail.dev
machinemail webhooks create --data @body.json

`API`

POST /v0/webhooks
POST /v0/inboxes/{inbox_id}/webhooks with --inbox
POST /v0/pods/{pod_id}/webhooks with --pod

`webhooks delete`

Delete webhook.

Also: machinemail webhooks rm.

Requires the webhook_delete permission.

machinemail webhooks delete <webhook-id> [flags]

`Arguments`

Field	Description
`<webhook-id>`	Required - ID of the webhook.

`Flags`

Field	Description
`--inbox <inbox-id>`	Use this inbox's scoped route.
`--pod <pod-id>`	Use this pod's scoped route.

`Examples`

machinemail webhooks delete whk_01m4g0b7r30000s9d4k1m6x2vn
machinemail webhooks delete whk_01m4g0b7r30000s9d4k1m6x2vn --inbox agent@machinemail.dev

`API`

DELETE /v0/webhooks/{webhook_id}
DELETE /v0/inboxes/{inbox_id}/webhooks/{webhook_id} with --inbox
DELETE /v0/pods/{pod_id}/webhooks/{webhook_id} with --pod

`webhooks deliveries`

List deliveries.

Delivery attempts of the webhook, one per event (a replay is a new delivery).

Requires the webhook_read permission.

machinemail webhooks deliveries <webhook-id> [flags]

`Arguments`

Field	Description
`<webhook-id>`	Required - ID of the webhook.

`Flags`

Field	Description
`--inbox <inbox-id>`	Only this inbox.
`--pod <pod-id>`	Only this pod.
`--limit <n>`	Maximum number of items to return. Default 50, maximum 500; larger values are capped.
`--page-token <value>`	next_page_token from the previous page.
`--ascending`	Sort oldest first.
`--status`	pending
`--all`	Follow next_page_token and return every page.

`Examples`

machinemail webhooks deliveries whk_01m4g0b7r30000s9d4k1m6x2vn
machinemail webhooks deliveries whk_01m4g0b7r30000s9d4k1m6x2vn --inbox agent@machinemail.dev
machinemail webhooks deliveries whk_01m4g0b7r30000s9d4k1m6x2vn --all --json | jq '.deliveries | length'

`API`

GET /v0/webhooks/{webhook_id}/deliveries
GET /v0/inboxes/{inbox_id}/webhooks/{webhook_id}/deliveries with --inbox
GET /v0/pods/{pod_id}/webhooks/{webhook_id}/deliveries with --pod

`webhooks get`

Get webhook.

Requires the webhook_read permission.

machinemail webhooks get <webhook-id> [flags]

`Arguments`

Field	Description
`<webhook-id>`	Required - ID of the webhook.

`Flags`

Field	Description
`--inbox <inbox-id>`	Only this inbox.
`--pod <pod-id>`	Only this pod.

`Examples`

machinemail webhooks get whk_01m4g0b7r30000s9d4k1m6x2vn
machinemail webhooks get whk_01m4g0b7r30000s9d4k1m6x2vn --inbox agent@machinemail.dev

`API`

GET /v0/webhooks/{webhook_id}
GET /v0/inboxes/{inbox_id}/webhooks/{webhook_id} with --inbox
GET /v0/pods/{pod_id}/webhooks/{webhook_id} with --pod

`webhooks headers`

Get webhook headers.

Names of the custom HTTP headers sent with every delivery to this webhook. Values are write-only and never returned.

Requires the webhook_read permission.

machinemail webhooks headers <webhook-id> [flags]

`Arguments`

Field	Description
`<webhook-id>`	Required - ID of the webhook.

`Flags`

Field	Description
`--inbox <inbox-id>`	Only this inbox.
`--pod <pod-id>`	Only this pod.

`Examples`

machinemail webhooks headers whk_01m4g0b7r30000s9d4k1m6x2vn
machinemail webhooks headers whk_01m4g0b7r30000s9d4k1m6x2vn --inbox agent@machinemail.dev

`API`

GET /v0/webhooks/{webhook_id}/headers
GET /v0/inboxes/{inbox_id}/webhooks/{webhook_id}/headers with --inbox
GET /v0/pods/{pod_id}/webhooks/{webhook_id}/headers with --pod

`webhooks list`

List webhooks.

Also: machinemail webhooks ls.

With an organization credential, every webhook of the organization, paginated. With a pod or inbox credential (or under a scoped path), the webhooks in that scope from the newest 500, in one page without next_page_token.

Requires the webhook_read permission.

machinemail webhooks list [flags]

`Flags`

Field	Description
`--inbox <inbox-id>`	Only this inbox.
`--pod <pod-id>`	Only this pod.
`--limit <n>`	Maximum number of items to return. Default 50, maximum 500; larger values are capped.
`--page-token <value>`	next_page_token from the previous page.
`--ascending`	Sort oldest first.
`--all`	Follow next_page_token and return every page.

`Examples`

machinemail webhooks list
machinemail webhooks list --inbox agent@machinemail.dev
machinemail webhooks list --all --json | jq '.webhooks | length'

`API`

GET /v0/webhooks
GET /v0/inboxes/{inbox_id}/webhooks with --inbox
GET /v0/pods/{pod_id}/webhooks with --pod

`webhooks replay`

Replay delivery.

Queues a new delivery of the same event to the webhook and attempts it right away, even when the webhook is disabled. Returns the new delivery after that attempt.

Requires the webhook_update permission.

machinemail webhooks replay <webhook-id> <delivery-id> [flags]

`Arguments`

Field	Description
`<webhook-id>`	Required - ID of the webhook.
`<delivery-id>`	Required - ID of the delivery to replay.

`Flags`

Field	Description
`--inbox <inbox-id>`	Use this inbox's scoped route.
`--pod <pod-id>`	Use this pod's scoped route.

`Examples`

machinemail webhooks replay whk_01m4g0b7r30000s9d4k1m6x2vn dlv_01m4g0c2p80000t5f7h3j9w1qb
machinemail webhooks replay whk_01m4g0b7r30000s9d4k1m6x2vn dlv_01m4g0c2p80000t5f7h3j9w1qb --inbox agent@machinemail.dev

`API`

`webhooks test`

Send test event.

Records a webhook.test event and delivers it to this webhook only (whatever its event_types, even when disabled), then returns the delivery after the first attempt.

Requires the webhook_update permission.

machinemail webhooks test <webhook-id> [flags]

`Arguments`

Field	Description
`<webhook-id>`	Required - ID of the webhook.

`Flags`

Field	Description
`--inbox <inbox-id>`	Use this inbox's scoped route.
`--pod <pod-id>`	Use this pod's scoped route.

`Examples`

machinemail webhooks test whk_01m4g0b7r30000s9d4k1m6x2vn
machinemail webhooks test whk_01m4g0b7r30000s9d4k1m6x2vn --inbox agent@machinemail.dev

`API`

POST /v0/webhooks/{webhook_id}/test
POST /v0/inboxes/{inbox_id}/webhooks/{webhook_id}/test with --inbox
POST /v0/pods/{pod_id}/webhooks/{webhook_id}/test with --pod

`webhooks update`

Update webhook.

Fields you omit are unchanged. Webhooks are never disabled automatically after failed deliveries; —enabled=false is the only way to disable one. New —event-types follow the same permission rule as POST /v0/webhooks, and changing —url needs the read permission of every event type the webhook delivers (403 otherwise).

—headers replaces the custom delivery headers in full, null or {} removes them, and omitting it keeps them. While a webhook has custom headers, changing —url to another origin (scheme, host or port) needs —headers in the same request (400 otherwise), so header values never follow the webhook to a new server unless you send them again.

Requires the webhook_update permission.

machinemail webhooks update <webhook-id> [flags]

`Arguments`

Field	Description
`<webhook-id>`	Required - ID of the webhook.

`Flags`

Field	Description
`--inbox <inbox-id>`	Use this inbox's scoped route.
`--pod <pod-id>`	Use this pod's scoped route.
`-e, --event-types`	Replaces the subscribed event types in full (not a merge). An empty array subscribes to every event type except domain.updated and trusted_domain.*, which are sent only when listed. Omit it to keep the types. Repeat the flag for several values.
`--enabled`	false disables the webhook: no new deliveries are queued (deliveries already queued are still attempted). true enables it again. Events that occurred while it was disabled are not delivered later.
`--add-inbox-ids <id>`	Inboxes to add to inbox_ids. Repeat the flag for several values.
`--remove-inbox-ids <id>`	Inboxes to remove from inbox_ids. Repeat the flag for several values.
`--add-pod-ids <id>`	Pods to add to pod_ids. Repeat the flag for several values.
`--remove-pod-ids <id>`	Pods to remove from pod_ids. Repeat the flag for several values.
`--url <url>`	New endpoint URL: a public http(s) URL.
`--headers <json>`	Replaces the custom delivery headers in full (not a merge): the webhook then sends exactly these. null or {} removes them all; omit it to keep them. To change one header and keep the others, use PATCH /v0/webhooks/{webhook_id}/headers. Values are write-only. At most 10 headers. Names are HTTP tokens of up to 64 characters, compared without regard to case; values are printable ASCII (no line breaks or control characters) of up to 4096 characters, with surrounding spaces removed, and names plus values total at most 8192 bytes. Reserved names are refused with 400: Host, Content-Length, Content-Type, Content-Encoding, Transfer-Encoding, Connection, Upgrade, TE, Trailer, Keep-Alive, Expect, User-Agent, Accept-Encoding, and every name starting with Proxy-, Sec-, X-MachineMail-, Svix- or Webhook-. Authorization and Cookie are allowed. null clears the value.
`--header <"Name: value">`	Custom delivery header "Name: value" (repeatable); replaces all custom headers. Value - reads stdin, env:VAR reads an environment variable (keeps secrets out of shell history). Repeat the flag for several values.
`--clear-headers`	Remove every custom delivery header (sends headers: null).
`-d, --data <json	@file

`Examples`

machinemail webhooks update whk_01m4g0b7r30000s9d4k1m6x2vn
machinemail webhooks update whk_01m4g0b7r30000s9d4k1m6x2vn --inbox agent@machinemail.dev
machinemail webhooks update whk_01m4g0b7r30000s9d4k1m6x2vn --data @body.json
machinemail webhooks update whk_01m4g0b7r30000s9d4k1m6x2vn --headers null   # clears headers

`API`

PATCH /v0/webhooks/{webhook_id}
PATCH /v0/inboxes/{inbox_id}/webhooks/{webhook_id} with --inbox
PATCH /v0/pods/{pod_id}/webhooks/{webhook_id} with --pod

`webhooks update-headers`

Update webhook headers.

Sets, replaces or removes custom delivery headers in one atomic change; headers you do not name keep their values. To replace the whole set (or clear it), use —headers on PATCH /v0/webhooks/{webhook_id}. Values remain write-only.

Requires the webhook_update permission.

machinemail webhooks update-headers <webhook-id> [flags]

`Arguments`

Field	Description
`<webhook-id>`	Required - ID of the webhook.

`Flags`

Field	Description
`--inbox <inbox-id>`	Use this inbox's scoped route.
`--pod <pod-id>`	Use this pod's scoped route.
`--headers <json>`	Custom HTTP headers sent with every delivery to this webhook (every attempt, retry, replay and test event), alongside the X-MachineMail-* headers, for example {"Authorization": "Bearer "} for an endpoint that requires one. Values are write-only: they are stored encrypted and no response returns them; reads list the names (header_names). The headers are not part of the signed payload: X-MachineMail-Signature covers the body only. At most 10 headers. Names are HTTP tokens of up to 64 characters, compared without regard to case; values are printable ASCII (no line breaks or control characters) of up to 4096 characters, with surrounding spaces removed, and names plus values total at most 8192 bytes. Reserved names are refused with 400: Host, Content-Length, Content-Type, Content-Encoding, Transfer-Encoding, Connection, Upgrade, TE, Trailer, Keep-Alive, Expect, User-Agent, Accept-Encoding, and every name starting with Proxy-, Sec-, X-MachineMail-, Svix- or Webhook-. Authorization and Cookie are allowed.
`--header <"Name: value">`	Header to set, as "Name: value" (repeatable); headers you do not name keep their values. Value - reads stdin, env:VAR reads an environment variable (keeps secrets out of shell history). Repeat the flag for several values.
`--remove-headers <value>`	Names of custom headers to remove (any case). Names that are not set are ignored. Repeat the flag for several values.
`-d, --data <json	@file