Sign in
Endpoints

Create a webhook endpoint

Changed on

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.

post/endpoints

Request

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

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 account-scoped name, required for kind=pull.

Response

Existing named pull destination resumed

successboolean required

Changes

  • 52138fa51360Revision changes
    • info

      removed the invalid_signup_code enum value from the / response property for the response status

    • info

      removed the invalid_signup_code enum value from the / response property for the response status

    • info

      removed the invalid_signup_code enum value from the / response property for the response status

    • info

      removed the invalid_signup_code enum value from the / response property for the response status

  • 22d1dfc68434Revision changes
    • warning

      added the new not_a_repeating_send enum value to the / response property for the response status

    • warning

      added the new not_a_repeating_send enum value to the / response property for the response status

    • warning

      added the new not_a_repeating_send enum value to the / response property for the response status

    • warning

      added the new not_a_repeating_send enum value to the / response property for the response status

    • warning

      added the new repeat_idle_requires_internal_recipient enum value to the / response property for the response status

    • warning

      added the new repeat_idle_requires_internal_recipient enum value to the / response property for the response status

    • warning

      added the new repeat_idle_requires_internal_recipient enum value to the / response property for the response status

    • warning

      added the new repeat_idle_requires_internal_recipient enum value to the / response property for the response status

    • warning

      added the new repeat_recipient_external enum value to the / response property for the response status

    • warning

      added the new repeat_recipient_external enum value to the / response property for the response status

    • warning

      added the new repeat_recipient_external enum value to the / response property for the response status

    • warning

      added the new repeat_recipient_external enum value to the / response property for the response status

    • warning

      added the new repeat_stop_not_allowed enum value to the / response property for the response status

    • warning

      added the new repeat_stop_not_allowed enum value to the / response property for the response status

    • warning

      added the new repeat_stop_not_allowed enum value to the / response property for the response status

    • warning

      added the new repeat_stop_not_allowed enum value to the / response property for the response status

    • warning

      added the new repeat_unsupported enum value to the / response property for the response status

    • warning

      added the new repeat_unsupported enum value to the / response property for the response status

    • warning

      added the new repeat_unsupported enum value to the / response property for the response status

    • warning

      added the new repeat_unsupported enum value to the / response property for the response status