SEsentdm
Webhooks

Create a webhook

Changed on

Creates a new webhook endpoint for the authenticated customer. A webhook is version 2 unless the request sets webhook_version to 1: Svix delivers it, signed with the webhook-id, webhook-timestamp and webhook-signature headers, and retries it on its own schedule, so retry_count and timeout_seconds apply to version 1 only. sender_profile applies to version 1 only and is ignored on version 2; is_inheritable applies to version 2 only. A version 1 webhook's response returns its sender_profile selection, with an empty event_types when it is not cloned onto sender profiles; a version 2 webhook's response leaves sender_profile out.

post/v3/webhooks

Request

  • Base URL
    https://api.sent.dm
  • URL
    https://api.sent.dm/v3/webhooks
  • Auth
    • API key in header x-api-key
    • or HTTP bearer

Headers

Idempotency-Keystring

Unique key to ensure idempotent request processing. Must be 1-255 alphanumeric characters, hyphens, or underscores. Responses are cached for 24 hours per key per customer.

x-profile-idstring uuid

Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.

Request body

sandboxboolean

Sandbox flag - when true, the operation is simulated without side effects Useful for testing integrations without actual execution

display_namestring required
endpoint_urlstring
event_typesstring[]
event_filtersobject nullable
retry_countinteger

Delivery retries. Applies to version 1 only: Svix retries a version 2 webhook on its own schedule.

timeout_secondsinteger

Delivery timeout. Applies to version 1 only.

webhook_versioninteger nullable

Who delivers the webhook: 2, the default, is delivered by Svix and signed with the webhook-id, webhook-timestamp and webhook-signature headers; 1 is the older delivery, signed with the X-Webhook-* headers, which will be retired.

is_inheritableboolean

Also delivers every sender profile's events to this webhook, at the same URL and with the same signing secret, and lets each profile see the webhook and read the events about itself. Off by default: the organization's own events only. Only an organization's version 2 webhook can set it.

Example request

{
  "display_name": "Order Notifications",
  "endpoint_url": "https://example.com/webhooks/orders",
  "event_types": [
    "contact",
    "message",
    "templates"
  ],
  "event_filters": {
    "message": [
      "delivered",
      "failed"
    ],
    "templates": [
      "approved",
      "rejected"
    ]
  },
  "retry_count": 3,
  "timeout_seconds": 30
}

Response

Webhook created successfully

successboolean

Indicates whether the request was successful

Changes

  • 41acb2ceb84dRevision changes
    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

  • 6c829543a93eRevision changes
    • breaking

      added subschema #2: SentDmServicesEndpointsCustomerAPIv3WebhooksRequestsCreateWebhookV3Request_Properties to the request body allOf list

    • breaking

      added to the response property oneOf list for the response status

    • breaking

      added to the response property oneOf list for the response status

    • breaking

      added to the response property oneOf list for the response status

    • warning

      removed subschema #2: SentDmServicesEndpointsCustomerAPIv3RequestsWebhooksCreateWebhookV3Request_Properties from the request body allOf list

    • info

      the endpoint scheme security BearerAuth was added to the API

    • info

      added to the response property allOf list for the response status

    • info

      added to the response property allOf list for the response status

    • info

      added to the response property allOf list for the response status

    • info

      added to the response property allOf list for the response status

    • info

      removed from the response property allOf list for the response status

    • info

      removed from the response property allOf list for the response status

    • info

      removed from the response property allOf list for the response status

    • info

      removed from the response property allOf list for the response status

    • info

      removed from the response property oneOf list for the response status

    • info

      removed from the response property oneOf list for the response status

    • info

      removed from the response property oneOf list for the response status