Docs
Sign in

Authentication

Updated May 31, 20262 min read

Your endpoint needs a way to verify that incoming webhook calls really come from Carriyo. Carriyo supports two authentication options per webhook configuration:

  • Static custom HTTP headers. Fixed header values you configure once.
  • OAuth2 client-credentials. Carriyo retrieves a token from your token endpoint and attaches it to each call.

Configure either option per webhook in the Dashboard under Settings → Webhooks.

Static custom headers

The simpler option. Configure one or more HTTP headers on the webhook and Carriyo includes them on every call. Common shapes:

  • An API key in a custom header: X-API-Key: your-key.
  • An HTTP Authorization header with a fixed token: Authorization: Bearer your-static-token or Authorization: ApiKey your-key.
  • Any other header your service expects for caller identification.

Your endpoint validates the header on receipt. If it doesn't match, return a 4xx response so Carriyo doesn't retry.

OAuth2 client-credentials

For systems that issue short-lived access tokens. You configure:

  • The token endpoint URL to call.
  • A client ID and client secret.
  • The content type for the token call (application/json or application/x-www-form-urlencoded).
  • Optionally, custom headers and custom parameters for the token call.

Carriyo's flow:

  1. POST to your token endpoint with grant_type=client_credentials, the client ID, the client secret, and any custom parameters you've added.
  2. Read the access_token and expires_in from the response.
  3. Cache the token until it expires.
  4. Attach Authorization: Bearer <token> to every webhook call.

When the cached token expires, Carriyo fetches a new one automatically. Your token endpoint is hit on cold-start and at expiry, not per webhook call.

Headers Carriyo sends with every delivery

Regardless of authentication choice, every webhook delivery carries the following metadata headers:

  • event-id: the unique id of the event being delivered. Stable across retries of the same event, so safe to use as an idempotency key.
  • trigger: which trigger fired this delivery (status change, label update, etc.).
  • webhook-id: the id of the webhook configuration that matched.
  • Content-Type and Content-Length: standard.

For retried deliveries, two additional headers appear:

  • retry-count: the current retry attempt number.
  • last-retry: true when this is the last automatic retry attempt.

Use event-id for idempotency keying. See Retry and idempotency.

How it fits with other modules