Skip to main content
Authsignal sends webhooks as signed JSON over HTTPS whenever a relevant event happens in your tenant. Your endpoint returns a 2xx response to acknowledge the event.

​
How to receive webhooks

​
1. Create an endpoint

In your application, create a route that accepts POST requests over HTTPS. For local development, expose your endpoint with a tunnel such as ngrok or Cloudflare Tunnel.

​
2. Configure the webhook URL

Webhook URLs are configured in different places depending on the event type.

​
3. Verify the signature

Every request is signed with an X-Signature-V2 header. Verify it before trusting the payload. See Verify webhook requests.

​
4. Handle the event

Inspect the envelope type and route to the right handler. Each event’s data schema is documented on its own page in this section.

​
Custom data points

Authenticator events can include values from your custom data points in data.customVariables, the same field that email.created uses. To include them:
  1. Register the data points you want to include as custom data points.
  2. In Tenant settings, open Webhooks.
  3. Under Authenticator events webhook URL, select Include custom data points.
  4. Select the data points to include, then save.
Each key in customVariables is the data point’s name, prefixed by its source:
  • User data points are prefixed with user_, such as user_accountId.
  • Action data points are prefixed with action_, such as action_transactionAmount.
Authsignal includes only the selected data points that have a value set on the user or the action. If none of them has a value, the event has no customVariables field. Action data points come from the action’s custom data, so an event carries them only if it happened during an action. Those events include actionCode and idempotencyKey. authenticator.expired never happens during an action, so it carries only user data points.
To set the data points with the Management API, send their IDs in authenticatorEventsWebhookConfig.allowedCustomVariables when you update the tenant. List Custom Data Points returns each data point’s ID. To keep the stored list, omit allowedCustomVariables. To stop including custom data points, send an empty array.