Skip to main content

Webhooks

Receive a POST every time a delivery's status changes. Twelve lifecycle events, one URL per environment, retried 3× over 60s on failure.

One URL + one Authentication Key/Value pair is allowed per environment (Sandbox or Production). Use webhooks instead of polling the Get Delivery endpoint.

Register an endpoint​

Webhooks are configured from the Dash Next Portal under Developers → Webhooks. Provide:

  • URL — your HTTPS endpoint that will receive the POST.
  • HTTP method — always POST.
  • Authentication Key + Authentication Value — optional but recommended (see next section).

Authenticating requests​

Unlike API calls (Bearer-token), Dash authenticates to your webhook URL using a custom header pair that you define in the Portal:

POST /your-webhook HTTP/1.1
Host: orders.example.com
Content-Type: application/json
{Authentication-Key}: {Authentication-Value}

You choose the header name (the Key) and a secret value. Dash sends the literal pair on every webhook call. See Securing endpoints for the recommended pattern.

Retry logic​

  • If your endpoint does not return a 2xx, Dash retries up to 3 times total with a 60-second interval between attempts.
  • After 3 failures the event is marked failed and dropped. Use Get Delivery to reconcile.
  • Retries apply to every webhook event, regardless of status.

Versioning​

The webhook contract is versioned in the API spec changelog. Breaking changes ship behind a major version bump; additive changes (new fields, new statuses) are rolled out without one. See the Changelog for v1 → v5 history.