> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Events and webhooks

> Separate Authentication activity, automatic monitoring delivery and application-submitted events without duplicating sign-ins.

<Warning>
  Automatic Authentication delivery to monitoring and `auth.*` webhooks are release-dependent. Current early-access sign-in activity is available through the Authentication management API. Its activity kinds are not a list of subscribable webhook types.
</Warning>

## Current activity catalogue

An authorized console session can read `GET /auth/v2/organizations/{org_id}/applications/{application_id}/authentication/sign-ins/` with `read:authentication`. Optional `kind` and `method` filters select exact values. End-user access tokens cannot read this management endpoint.

| Activity kind | Recorded action |
| - | - |
| `auth.sign_in` | A successful sign-in creates a session. |
| `auth.sign_in_failed` | A supported sign-in proof fails. An identity is not always known. |
| `auth.session_revoked` | A session is revoked, including through logout. |
| `auth.password_changed` | A password reset completes. |
| `auth.two_factor_changed` | An authenticator is enabled. |
| `auth.invitation_accepted` | A customer invitation is accepted. |

Do not infer a separate sign-up or forgot-password event from the presence of a sign-in or password-change event. Do not assume every failure occurs after the user has been identified.

## Automatic delivery release contract

The upcoming integration sends Authentication events to monitoring automatically, with the person's stable `vendor_data` and available device context. Your app must not submit a duplicate login event for an action already emitted by Didit Authentication.

| User action | Planned coverage |
| - | - |
| Sign-up and successful login | Identity creation and sign-in activity. |
| Failed login and account lock | Failed proof and lock activity, with identity only when known. |
| Logout | Session revocation activity. |
| Forgot and reset password | Request and completion activity. |
| MFA changes | Factor changes. |
| Device change | New-device activity. |

Exact public webhook type names and payload schemas will be documented when delivery is available. Do not translate these labels into guessed `auth.*` subscriptions. Automatic auth activity is intended to be billed by active user, not by event; no price is specified here.

## Application-submitted events

For actions your application owns, the current server lane is `POST https://verification.didit.me/v3/events/` or `/v3/events/batch/` with `x-api-key`. Event monitoring must be enabled. Keep the API key on your server.

The device lane uses a scoped `monitoring_token` from `POST /v3/events/sdk-token/`, sent in `X-Monitoring-Token` to `/v1/events/` or `/v1/events/batch/`. Your backend binds it to the authenticated person's `vendor_data`. A transaction token is a different credential; do not substitute `X-Transaction-Token`.

The separate `@didit-protocol/signals` package and `DiditSdk.shared.submitEvent` are release-dependent. Until their exports and version are published, use the documented server contract for your deployment rather than inventing SDK arguments. Events are not financial transactions: use [transaction submission](/transaction-monitoring/sdk-transaction-submission) for those.

## Receive product webhooks

Use the existing [webhook receiver guide](/integration/webhooks) for available event types, signature verification and retries. Authenticate the entire payload with `X-Signature-V2`, enforce `X-Timestamp` freshness, and deduplicate `event_id` durably before applying side effects. Acknowledge only after durable acceptance and process expensive work asynchronously.

A verification callback or SDK completion is not a trusted final decision. Fetch the server result or consume a verified webhook. Authentication webhook subscriptions must stay disabled until the destination API explicitly supports them; do not silently count an unconfigured subscription as working.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.