> This page is for version V3 - Beta (default).
> For other versions, use one of these documentation indexes:
> - V3 - Beta (default): https://docs.authlyx.dev/v3/llms.txt
> - V2 - Legacy: https://docs.authlyx.dev/v2/llms.txt
> - V1 - End of support: https://docs.authlyx.dev/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.authlyx.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.authlyx.dev/_mcp/server.

# Webhooks

> Send app and account events from AuthlyX to your server.

Suppose a customer buys a license and your own order system needs to mark it as delivered. Add a webhook destination for your server and select `license.created`. When AuthlyX creates a license, it sends a signed request to that URL. Your server can record the event without polling AuthlyX every minute.

```mermaid
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#ffffff","primaryTextColor":"#171717","primaryBorderColor":"#404040","lineColor":"#606060","secondaryColor":"#f5f5f5","tertiaryColor":"#ffffff","edgeLabelBackground":"#ffffff"}}}%%
sequenceDiagram
  participant A as AuthlyX dashboard or API
  participant Q as AuthlyX delivery queue
  participant S as Your server
  A->>Q: license.created
  Q->>S: Signed HTTPS request
  S->>S: Verify signature and check event ID
  S-->>Q: 2xx after accepting event
```

## Add a destination

1. Open **Webhooks** for the app and add a destination name, such as `Northstar Orders`.
2. Enter an HTTPS URL on your server.
3. Create and save a signing secret. Keep it on your server; AuthlyX does not need to show it again after setup.
4. Choose only the events your server needs. For example, use `license.created`, `identity.paused` and `plan.updated` if you synchronize license delivery and plan changes.
5. Send a test delivery. Check its status and response under **Deliveries**.

One app can have several destinations. For example, send license events to your order system and audit events to a separate monitoring service. Each destination has its own URL, secret and event list.

## Verify before acting

Treat every webhook request as untrusted until its signature passes. Read the exact raw request body, then calculate HMAC-SHA256 using that destination's secret over `timestamp + "." + rawBody`. Compare the result with the `v1=...` value in `X-AuthlyX-Signature`, and check that `X-AuthlyX-Timestamp` is recent. Verify the signature before parsing and using the event fields.

Save each event ID before processing it. AuthlyX retries temporary delivery failures, so the same event can arrive more than once. If your server already processed that event ID, return a 2xx response without repeating the action.

## If your server is down

Return a non-2xx response when your server has not safely accepted the event. AuthlyX records the attempt and retries temporary failures. Use the Deliveries page to see status, response code and attempts, then retry where available.

Webhooks are useful for synchronizing your own services. They do not replace a live access check when a customer signs in. The SDK should still ask AuthlyX whether the license, user or device may access the app.