Skip to navigation
API ReferenceInboxesWebhooks

Create Webhook

Create a webhook scoped to this inbox.

CLI:

agentmail inboxes webhooks create --inbox-id <inbox_id> --url https://example.com/webhook --event-types message.received

Authentication

AuthorizationBearer

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

Path parameters

inbox_idstringRequired
The ID of the inbox.

Request

This endpoint expects an object.
urlstringRequired
URL of webhook endpoint.
event_typeslist of enumsRequired

Full list of event types this webhook should receive. Required: omitting it or sending an empty array returns a 400, and there is no “all events” default. Send every type you want in this array (not incremental). See Webhooks overview for spam, blocked, and unauthenticated events and required permissions.

client_idstringOptional
Client ID of webhook.
headersmap from strings to stringsOptional

Custom HTTP headers to include with every delivery to this webhook. Header values are write-only: AgentMail never returns them from webhook read endpoints. The map must contain at least one entry when provided, and every name and value must be a valid HTTP header.

Response

This endpoint returns an object.
webhook_idstring
ID of webhook.
urlstring
URL of webhook endpoint.
secretstring
Secret for webhook signature verification.
enabledboolean

Whether the webhook is enabled. It becomes false when you disable it, and also when deliveries to the URL have failed for 5 days, in which case AgentMail sends no notification. Re-enable it with update and enabled set to true.

updated_atdatetime
Time at which webhook was last updated.
created_atdatetime
Time at which webhook was created.
event_typeslist of enumsOptional
Event types for which to send events.
pod_idslist of stringsOptional
Pods for which to send events.
inbox_idslist of stringsOptional
Inboxes for which to send events.
pod_idstringOptional

ID of the pod the webhook belongs to: the pod it was created in, or the pod of the inbox it belongs to. Absent for an organization webhook and on some inbox webhooks. This is not the list of pods it receives events for; see pod_ids.

inbox_idstringOptional

ID of the inbox the webhook belongs to, if it was created for an inbox. This is not the list of inboxes it receives events for; see inbox_ids.

client_idstringOptional
Client ID of webhook.

Errors

400
Validation Error