webhooks · MachineMail Docs

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 list`	List webhooks
`webhooks replay`	Replay delivery
`webhooks test`	Send test event
`webhooks update`	Update webhook

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 delivery headers are not supported.

Requires the webhook_create permission.

shell

machinemail webhooks create [flags]

Flags

--inbox <inbox-id>string

Create it in this inbox.

--pod <pod-id>string

Create it in this pod.

--url <url>string

Endpoint URL: a public http(s) URL (private and loopback addresses are rejected, and re-checked before every delivery).

-e, --event-typesstring[]

Event types the webhook receives. Omit it or send an empty array to receive every event type except domain.updated, which is sent only when listed. Repeat the flag for several values.

--client-id <id>string

Idempotency key: a create with a --client-id already used in the organization returns that webhook with 200.

-d, --data <json|@file|->string

Request body as JSON, @file or - for stdin; field flags override its keys.

Examples

shell

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.

shell

machinemail webhooks delete <webhook-id> [flags]

Arguments

<webhook-id>stringRequired

ID of the webhook.

Flags

--inbox <inbox-id>string

Use this inbox's scoped route.

--pod <pod-id>string

Use this pod's scoped route.

Examples

shell

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.

shell

machinemail webhooks deliveries <webhook-id> [flags]

Arguments

<webhook-id>stringRequired

ID of the webhook.

Flags

--inbox <inbox-id>string

Only this inbox.

--pod <pod-id>string

Only this pod.

--limit <n>integer

Maximum number of items to return. Default 50, maximum 500; larger values are capped.

Default50

--page-token <value>string

next_page_token from the previous page.

--ascendingboolean

Sort oldest first.

--statuspending | delivered | failed

Only deliveries with this status.

--allboolean

Follow next_page_token and return every page.

Examples

shell

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.

shell

machinemail webhooks get <webhook-id> [flags]

Arguments

<webhook-id>stringRequired

ID of the webhook.

Flags

--inbox <inbox-id>string

Only this inbox.

--pod <pod-id>string

Only this pod.

Examples

shell

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 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.

shell

machinemail webhooks list [flags]

Flags

--inbox <inbox-id>string

Only this inbox.

--pod <pod-id>string

Only this pod.

--limit <n>integer

Maximum number of items to return. Default 50, maximum 500; larger values are capped.

Default50

--page-token <value>string

next_page_token from the previous page.

--ascendingboolean

Sort oldest first.

--allboolean

Follow next_page_token and return every page.

Examples

shell

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.

shell

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

Arguments

<webhook-id>stringRequired

ID of the webhook.

<delivery-id>stringRequired

ID of the delivery to replay.

Flags

--inbox <inbox-id>string

Use this inbox's scoped route.

--pod <pod-id>string

Use this pod's scoped route.

Examples

shell

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.

shell

machinemail webhooks test <webhook-id> [flags]

Arguments

<webhook-id>stringRequired

ID of the webhook.

Flags

--inbox <inbox-id>string

Use this inbox's scoped route.

--pod <pod-id>string

Use this pod's scoped route.

Examples

shell

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).

Requires the webhook_update permission.

shell

machinemail webhooks update <webhook-id> [flags]

Arguments

<webhook-id>stringRequired

ID of the webhook.

Flags

--inbox <inbox-id>string

Use this inbox's scoped route.

--pod <pod-id>string

Use this pod's scoped route.

-e, --event-typesstring[]

Replaces the subscribed event types in full (not a merge). An empty array subscribes to every event type except domain.updated, which is sent only when listed. Omit it to keep the types. Repeat the flag for several values.

--enabledboolean

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>string[]

Inboxes to add to inbox_ids. Repeat the flag for several values.

--remove-inbox-ids <id>string[]

Inboxes to remove from inbox_ids. Repeat the flag for several values.

--add-pod-ids <id>string[]

Pods to add to pod_ids. Repeat the flag for several values.

--remove-pod-ids <id>string[]

Pods to remove from pod_ids. Repeat the flag for several values.

--url <url>string

New endpoint URL: a public http(s) URL.

-d, --data <json|@file|->string

Request body as JSON, @file or - for stdin; field flags override its keys.

Examples

shell

machinemail webhooks update whk_01m4g0b7r30000s9d4k1m6x2vn
machinemail webhooks update whk_01m4g0b7r30000s9d4k1m6x2vn --inbox agent@machinemail.dev
machinemail webhooks update whk_01m4g0b7r30000s9d4k1m6x2vn --data @body.json

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