Account8

Address Notes7

Agent7

Agent Connections13

Agent Networks8

Changes1

CLI6

Contacts13

Credentials13

Credits2

Discovery2

Domains10

Email Rules7

Emails14

Endpoints8

Filters4

Functions40

Inbox7

Interactions4

Mailbox access6

Memories4

Organization settings12

Organizations3

Projects9

Repeating Sends5

Roles and members18

Routes6

Search1

Sending20

Service1

Stats3

Templates3

Threads6

Wake11

Webhook Deliveries3

Endpoints

Create a webhook endpoint

Changed on Nov 3, 2026

Creates a new webhook endpoint. If a deactivated endpoint with the same URL and domain exists, it is reactivated instead. Subject to plan limits on the number of active endpoints.

Signing is account-scoped, not per-endpoint. This call does not return any signing material; every endpoint on the account uses the same webhook secret, fetched via GET /account/webhook-secret. See the API-level "Webhook signing" section for the full wire format (header name, signed string, hash algo, secret format, tolerance) and a language-agnostic verification recipe.

After creating the endpoint, fire a test delivery against it via POST /endpoints/{id}/test to confirm your verifier accepts the signature.

For local receiving, use kind=pull and a stable name, without url, function_id or domain_id. Named creation resumes the same active destination; omitted filters preserve its selection, while conflicting supplied configuration returns 409. New unfiltered destinations receive all subsequently ready eligible event types within their credential scope. Connected-agent credentials automatically create private subscriptions restricted to inbound email for their assigned address. Names are isolated per credential; revocation or replacement deletes its subscriptions. Address-scoped events contain parsed mail without raw MIME, signed download links, routing metadata, or sibling envelope recipients. Pull destinations do not occupy HTTP routing slots. Signing-secret setup and a test HTTP delivery are not required for pull receiving.

For local receiving, use kind=pull and a stable name, without url, function_id or domain_id. Named creation resumes the same active destination; omitted filters preserve its selection, while conflicting supplied configuration returns 409. Creating a pull destination requires a connected-agent credential; it creates a private subscription restricted to inbound email for the assigned address of that credential. Account API keys receive 403 pull_subscription_requires_agent_connection and can instead receive mail with GET /emails?since=<cursor>&wait=30 or an HTTP endpoint. Pulling or completing an account destination created earlier returns the same 403. Names are isolated per credential; revocation or replacement deletes its subscriptions. Address-scoped events contain parsed mail without raw MIME, signed download links, routing metadata, or sibling envelope recipients. Pull destinations do not occupy HTTP routing slots. Signing-secret setup and a test HTTP delivery are not required for pull receiving.

Agent connection keys (pconn_) may use endpoints.pull:manage instead of endpoints:manage here, for their own pull subscriptions only.

post/endpoints

Request

Base URL
https://api.primitive.dev/v1
URL
https://api.primitive.dev/v1/endpoints
Auth
HTTP bearer

Headers

Idempotency-Keystring

Optional client-supplied idempotency key. Retrying a request with the same key returns the original result instead of performing the action a second time; if omitted the server derives one from the canonical payload hash. Safe to retry network failures without duplicating side effects.

Request body

kind'http' | 'function' | 'pull'

http: deliver to url. function: invoke function_id. pull: receive locally using a stable name, without a URL.

urlstring

The webhook URL to deliver events to. Required when kind is http; omit for function endpoints.

function_idstring uuid

The Function to invoke. Required when kind is function.

enabledboolean

Whether the endpoint is active

domain_idstring uuid nullable

Restrict to emails from a specific domain

is_route_targetboolean

Create this endpoint as a route-target: reachable only via an explicit recipient route, never a domain's default destination, and exempt from the one-endpoint-per-domain rule.

namestring

Stable name within the credential scope, required for kind=pull. Only connected-agent credentials can create pull destinations, and each receives only its assigned address.

takeoverboolean

When the domain (or, with no domain_id, the organization's fallback slot) already has an active endpoint: false (the default) answers 409 conflict with details.holder naming it; true retires that endpoint in the same request, after the checks deleting it would need. Route targets and pull destinations never hold the slot. A plan limit (one fallback webhook on the free plan, Power for per-domain webhooks) is checked first, and takeover lifts only the fallback limit the holder itself would count against.

owner_key_idstring uuid

Make this webhook owned by an API key of the organization instead of by the organization. It receives the mail recipient routes send to it and interaction events for addresses the key reads, each checked against the key: only mail the key can read is sent, and nothing while the key is revoked or suspended. It is never a domain or organization default: it is created as a route target, and is_route_target false or takeover is refused. Not a connected agent key or a Function key.

Response

Existing named pull destination resumed

successtrue required

Changes

Nov 3, 2026bce409c97acb Revision changes
- warning
  added the new access_mode_unavailable enum value to the / response property for the response status
- warning
  added the new access_mode_unavailable enum value to the / response property for the response status
- warning
  added the new access_mode_unavailable enum value to the / response property for the response status
- warning
  added the new access_mode_unavailable enum value to the / response property for the response status
- warning
  added the new access_mode_unavailable enum value to the / response property for the response status
- warning
  added the new builtin_role enum value to the / response property for the response status
- warning
  added the new builtin_role enum value to the / response property for the response status
- warning
  added the new builtin_role enum value to the / response property for the response status
- warning
  added the new builtin_role enum value to the / response property for the response status
- warning
  added the new builtin_role enum value to the / response property for the response status
- warning
  added the new cleanup_incomplete enum value to the / response property for the response status
- warning
  added the new cleanup_incomplete enum value to the / response property for the response status
- warning
  added the new cleanup_incomplete enum value to the / response property for the response status
- warning
  added the new cleanup_incomplete enum value to the / response property for the response status
- warning
  added the new cleanup_incomplete enum value to the / response property for the response status
- warning
  added the new cli_access_refused enum value to the / response property for the response status
- warning
  added the new cli_access_refused enum value to the / response property for the response status
- warning
  added the new cli_access_refused enum value to the / response property for the response status
- warning
  added the new cli_access_refused enum value to the / response property for the response status
- warning
  added the new cli_access_refused enum value to the / response property for the response status
- warning
  added the new confirmation_required enum value to the / response property for the response status
- warning
  added the new confirmation_required enum value to the / response property for the response status
- warning
  added the new confirmation_required enum value to the / response property for the response status
- warning
  added the new confirmation_required enum value to the / response property for the response status
- warning
  added the new confirmation_required enum value to the / response property for the response status
- warning
  added the new connection_owner_address_required enum value to the / response property for the response status
- warning
  added the new connection_owner_address_required enum value to the / response property for the response status
- warning
  added the new connection_owner_address_required enum value to the / response property for the response status
- warning
  added the new connection_owner_address_required enum value to the / response property for the response status
- warning
  added the new connection_owner_address_required enum value to the / response property for the response status
- warning
  added the new email_rule_author_only enum value to the / response property for the response status
- warning
  added the new email_rule_author_only enum value to the / response property for the response status
- warning
  added the new email_rule_author_only enum value to the / response property for the response status
- warning
  added the new email_rule_author_only enum value to the / response property for the response status
- warning
  added the new email_rule_author_only enum value to the / response property for the response status
- warning
  added the new email_rule_compiler_unavailable enum value to the / response property for the response status
- warning
  added the new email_rule_compiler_unavailable enum value to the / response property for the response status
- warning
  added the new email_rule_compiler_unavailable enum value to the / response property for the response status
- warning
  added the new email_rule_compiler_unavailable enum value to the / response property for the response status
- warning
  added the new email_rule_compiler_unavailable enum value to the / response property for the response status
- warning
  added the new email_rule_conflict enum value to the / response property for the response status
- warning
  added the new email_rule_conflict enum value to the / response property for the response status
- warning
  added the new email_rule_conflict enum value to the / response property for the response status
- warning
  added the new email_rule_conflict enum value to the / response property for the response status
- warning
  added the new email_rule_conflict enum value to the / response property for the response status
- warning
  added the new email_rule_not_compiled enum value to the / response property for the response status
- warning
  added the new email_rule_not_compiled enum value to the / response property for the response status
- warning
  added the new email_rule_not_compiled enum value to the / response property for the response status
- warning
  added the new email_rule_not_compiled enum value to the / response property for the response status
- warning
  added the new email_rule_not_compiled enum value to the / response property for the response status
- warning
  added the new grant_forbidden enum value to the / response property for the response status
- warning
  added the new grant_forbidden enum value to the / response property for the response status
- warning
  added the new grant_forbidden enum value to the / response property for the response status
- warning
  added the new grant_forbidden enum value to the / response property for the response status
- warning
  added the new grant_forbidden enum value to the / response property for the response status
- warning
  added the new keep_refused enum value to the / response property for the response status
- warning
  added the new keep_refused enum value to the / response property for the response status
- warning
  added the new keep_refused enum value to the / response property for the response status
- warning
  added the new keep_refused enum value to the / response property for the response status
- warning
  added the new keep_refused enum value to the / response property for the response status
- warning
  added the new last_owner enum value to the / response property for the response status
- warning
  added the new last_owner enum value to the / response property for the response status
- warning
  added the new last_owner enum value to the / response property for the response status
- warning
  added the new last_owner enum value to the / response property for the response status
- warning
  added the new last_owner enum value to the / response property for the response status
- warning
  added the new mailbox_not_claimable enum value to the / response property for the response status
- warning
  added the new mailbox_not_claimable enum value to the / response property for the response status
- warning
  added the new mailbox_not_claimable enum value to the / response property for the response status
- warning
  added the new mailbox_not_claimable enum value to the / response property for the response status
- warning
  added the new mailbox_not_claimable enum value to the / response property for the response status
- warning
  added the new mailbox_shared_with_others enum value to the / response property for the response status
- warning
  added the new mailbox_shared_with_others enum value to the / response property for the response status
- warning
  added the new mailbox_shared_with_others enum value to the / response property for the response status
- warning
  added the new mailbox_shared_with_others enum value to the / response property for the response status
- warning
  added the new mailbox_shared_with_others enum value to the / response property for the response status
- warning
  added the new member_address_reserved enum value to the / response property for the response status
- warning
  added the new member_address_reserved enum value to the / response property for the response status
- warning
  added the new member_address_reserved enum value to the / response property for the response status
- warning
  added the new member_address_reserved enum value to the / response property for the response status
- warning
  added the new member_address_reserved enum value to the / response property for the response status
- warning
  added the new plan_required enum value to the / response property for the response status
- warning
  added the new plan_required enum value to the / response property for the response status
- warning
  added the new plan_required enum value to the / response property for the response status
- warning
  added the new plan_required enum value to the / response property for the response status
- warning
  added the new plan_required enum value to the / response property for the response status
- warning
  added the new redeploy_failed enum value to the / response property for the response status
- warning
  added the new redeploy_failed enum value to the / response property for the response status
- warning
  added the new redeploy_failed enum value to the / response property for the response status
- warning
  added the new redeploy_failed enum value to the / response property for the response status
- warning
  added the new redeploy_failed enum value to the / response property for the response status
- warning
  added the new removal_failed enum value to the / response property for the response status
- warning
  added the new removal_failed enum value to the / response property for the response status
- warning
  added the new removal_failed enum value to the / response property for the response status
- warning
  added the new removal_failed enum value to the / response property for the response status
- warning
  added the new removal_failed enum value to the / response property for the response status
- warning
  added the new removal_timeout enum value to the / response property for the response status
- warning
  added the new removal_timeout enum value to the / response property for the response status
- warning
  added the new removal_timeout enum value to the / response property for the response status
- warning
  added the new removal_timeout enum value to the / response property for the response status
- warning
  added the new removal_timeout enum value to the / response property for the response status
- warning
  added the new role_assigned enum value to the / response property for the response status
- warning
  added the new role_assigned enum value to the / response property for the response status
- warning
  added the new role_assigned enum value to the / response property for the response status
- warning
  added the new role_assigned enum value to the / response property for the response status
- warning
  added the new role_assigned enum value to the / response property for the response status
- warning
  added the new role_assignment_unavailable enum value to the / response property for the response status
- warning
  added the new role_assignment_unavailable enum value to the / response property for the response status
- warning
  added the new role_assignment_unavailable enum value to the / response property for the response status
- warning
  added the new role_assignment_unavailable enum value to the / response property for the response status
- warning
  added the new role_assignment_unavailable enum value to the / response property for the response status
- warning
  added the new role_key_taken enum value to the / response property for the response status
- warning
  added the new role_key_taken enum value to the / response property for the response status
- warning
  added the new role_key_taken enum value to the / response property for the response status
- warning
  added the new role_key_taken enum value to the / response property for the response status
- warning
  added the new role_key_taken enum value to the / response property for the response status
- warning
  added the new rotation_in_progress enum value to the / response property for the response status
- warning
  added the new rotation_in_progress enum value to the / response property for the response status
- warning
  added the new rotation_in_progress enum value to the / response property for the response status
- warning
  added the new rotation_in_progress enum value to the / response property for the response status
- warning
  added the new rotation_in_progress enum value to the / response property for the response status
- warning
  added the new rotation_incomplete enum value to the / response property for the response status
- warning
  added the new rotation_incomplete enum value to the / response property for the response status
- warning
  added the new rotation_incomplete enum value to the / response property for the response status
- warning
  added the new rotation_incomplete enum value to the / response property for the response status
- warning
  added the new rotation_incomplete enum value to the / response property for the response status
- warning
  added the new step_up_invalid enum value to the / response property for the response status
- warning
  added the new step_up_invalid enum value to the / response property for the response status
- warning
  added the new step_up_invalid enum value to the / response property for the response status
- warning
  added the new step_up_invalid enum value to the / response property for the response status
- warning
  added the new step_up_invalid enum value to the / response property for the response status
- warning
  added the new step_up_not_accepted enum value to the / response property for the response status
- warning
  added the new step_up_not_accepted enum value to the / response property for the response status
- warning
  added the new step_up_not_accepted enum value to the / response property for the response status
- warning
  added the new step_up_not_accepted enum value to the / response property for the response status
- warning
  added the new step_up_not_accepted enum value to the / response property for the response status
- warning
  added the new step_up_refused enum value to the / response property for the response status
- warning
  added the new step_up_refused enum value to the / response property for the response status
- warning
  added the new step_up_refused enum value to the / response property for the response status
- warning
  added the new step_up_refused enum value to the / response property for the response status
- warning
  added the new step_up_refused enum value to the / response property for the response status
- warning
  added the new step_up_required enum value to the / response property for the response status
- warning
  added the new step_up_required enum value to the / response property for the response status
- warning
  added the new step_up_required enum value to the / response property for the response status
- warning
  added the new step_up_required enum value to the / response property for the response status
- warning
  added the new step_up_required enum value to the / response property for the response status
- warning
  added the new template_role enum value to the / response property for the response status
- warning
  added the new template_role enum value to the / response property for the response status
- warning
  added the new template_role enum value to the / response property for the response status
- warning
  added the new template_role enum value to the / response property for the response status
- warning
  added the new template_role enum value to the / response property for the response status
- warning
  added the new upstream_unavailable enum value to the / response property for the response status
- warning
  added the new upstream_unavailable enum value to the / response property for the response status
- warning
  added the new upstream_unavailable enum value to the / response property for the response status
- warning
  added the new upstream_unavailable enum value to the / response property for the response status
- warning
  added the new upstream_unavailable enum value to the / response property for the response status
This list may be incomplete.
Oct 21, 20260360ea8d4f3d Revision changes
- warning
  added the new agent_changed enum value to the / response property for the response status
- warning
  added the new agent_changed enum value to the / response property for the response status
- warning
  added the new agent_changed enum value to the / response property for the response status
- warning
  added the new agent_changed enum value to the / response property for the response status
- warning
  added the new agent_changed enum value to the / response property for the response status
- warning
  added the new agent_limit enum value to the / response property for the response status
- warning
  added the new agent_limit enum value to the / response property for the response status
- warning
  added the new agent_limit enum value to the / response property for the response status
- warning
  added the new agent_limit enum value to the / response property for the response status
- warning
  added the new agent_limit enum value to the / response property for the response status
- warning
  added the new already_member enum value to the / response property for the response status
- warning
  added the new already_member enum value to the / response property for the response status
- warning
  added the new already_member enum value to the / response property for the response status
- warning
  added the new already_member enum value to the / response property for the response status
- warning
  added the new already_member enum value to the / response property for the response status
- warning
  added the new directory_limit enum value to the / response property for the response status
- warning
  added the new directory_limit enum value to the / response property for the response status
- warning
  added the new directory_limit enum value to the / response property for the response status
- warning
  added the new directory_limit enum value to the / response property for the response status
- warning
  added the new directory_limit enum value to the / response property for the response status
- warning
  added the new invitation_accepted enum value to the / response property for the response status
- warning
  added the new invitation_accepted enum value to the / response property for the response status
- warning
  added the new invitation_accepted enum value to the / response property for the response status
- warning
  added the new invitation_accepted enum value to the / response property for the response status
- warning
  added the new invitation_accepted enum value to the / response property for the response status
- warning
  added the new invitation_changed enum value to the / response property for the response status
- warning
  added the new invitation_changed enum value to the / response property for the response status
- warning
  added the new invitation_changed enum value to the / response property for the response status
- warning
  added the new invitation_changed enum value to the / response property for the response status
- warning
  added the new invitation_changed enum value to the / response property for the response status
- warning
  added the new invitation_pending enum value to the / response property for the response status
- warning
  added the new invitation_pending enum value to the / response property for the response status
- warning
  added the new invitation_pending enum value to the / response property for the response status
- warning
  added the new invitation_pending enum value to the / response property for the response status
- warning
  added the new invitation_pending enum value to the / response property for the response status
- warning
  added the new invitation_sending enum value to the / response property for the response status
- warning
  added the new invitation_sending enum value to the / response property for the response status
- warning
  added the new invitation_sending enum value to the / response property for the response status
- warning
  added the new invitation_sending enum value to the / response property for the response status
- warning
  added the new invitation_sending enum value to the / response property for the response status
- warning
  added the new invitation_unconfirmed enum value to the / response property for the response status
- warning
  added the new invitation_unconfirmed enum value to the / response property for the response status
- warning
  added the new invitation_unconfirmed enum value to the / response property for the response status
- warning
  added the new invitation_unconfirmed enum value to the / response property for the response status
- warning
  added the new invitation_unconfirmed enum value to the / response property for the response status
- warning
  added the new invitations_pending enum value to the / response property for the response status
- warning
  added the new invitations_pending enum value to the / response property for the response status
- warning
  added the new invitations_pending enum value to the / response property for the response status
- warning
  added the new invitations_pending enum value to the / response property for the response status
- warning
  added the new invitations_pending enum value to the / response property for the response status
- warning
  added the new member_changed enum value to the / response property for the response status
- warning
  added the new member_changed enum value to the / response property for the response status
- warning
  added the new member_changed enum value to the / response property for the response status
- warning
  added the new member_changed enum value to the / response property for the response status
- warning
  added the new member_changed enum value to the / response property for the response status
- warning
  added the new project_changed enum value to the / response property for the response status
- warning
  added the new project_changed enum value to the / response property for the response status
- warning
  added the new project_changed enum value to the / response property for the response status
- warning
  added the new project_changed enum value to the / response property for the response status
- warning
  added the new project_changed enum value to the / response property for the response status
- warning
  added the new recipient_changed enum value to the / response property for the response status
- warning
  added the new recipient_changed enum value to the / response property for the response status
- warning
  added the new recipient_changed enum value to the / response property for the response status
- warning
  added the new recipient_changed enum value to the / response property for the response status
- warning
  added the new recipient_changed enum value to the / response property for the response status

Operation history (13 revisions)