All Docs
FeaturesagentOS Direct DebitUpdated March 13, 2026

Stripe Identity Webhook Ingestion

Stripe Identity Webhook Ingestion

Available from: v1.0.36

Overview

The Direct Debit service uses Stripe Identity to verify the identity of tenants during mandate setup (Step 6 of the mandate form). From v1.0.36, the result of that verification is automatically ingested via Stripe's webhook system, updating the mandate's verification status and driving the next step in the mandate lifecycle — without any manual intervention.

How It Works

1. Verification Session Created (Form Step 6)

When a tenant reaches Step 6 of the mandate form (ID Verification), a Stripe Identity verification session is created and its session ID is stored against the mandate record. The tenant completes the verification flow on Stripe's hosted UI.

2. Stripe Sends a Webhook

Once Stripe processes the verification, it dispatches a webhook event to:

POST /api/webhooks/stripe

Two Identity events are now handled:

EventMeaning
identity.verification_session.verifiedThe tenant's identity was successfully verified.
identity.verification_session.requires_inputVerification could not be completed — further input or a retry is required.

3. Mandate Lookup

The webhook handler extracts the verification_session.id from the event payload and looks up the mandate that was associated with that session ID during form submission.

4. Status Update

The mandate's id_verification_status field is updated to reflect the outcome:

  • verified — identity check passed.
  • requires_input — identity check did not pass; the mandate cannot proceed until this is resolved.

5. Flow Continuation or Rejection

Depending on the updated status, the service automatically triggers the appropriate next step:

  • Verified → The mandate continues through the activation pipeline (e.g. AUDDIS submission to Modulr).
  • Requires input → The mandate is flagged for rejection; the consuming application (e.g. agentOS) can retrieve this status via the mandate API and take appropriate action, such as notifying the tenant or blocking access.

Webhook Endpoint

POST /api/webhooks/stripe

This is a shared Stripe webhook endpoint. It handles all Stripe event types routed to the service, including payment events and (from v1.0.36) Stripe Identity events.

Relevant Stripe Identity Event Payloads

identity.verification_session.verified

{
  "type": "identity.verification_session.verified",
  "data": {
    "object": {
      "id": "vs_xxxxxxxxxxxxxxxxxx",
      "status": "verified",
      ...
    }
  }
}

identity.verification_session.requires_input

{
  "type": "identity.verification_session.requires_input",
  "data": {
    "object": {
      "id": "vs_xxxxxxxxxxxxxxxxxx",
      "status": "requires_input",
      "last_error": {
        "code": "document_expired",
        "reason": "The provided identity document has expired."
      },
      ...
    }
  }
}

Mandate id_verification_status Field

The mandate record exposes an id_verification_status field that reflects the current state of the Stripe Identity check:

ValueDescription
pendingVerification session created; awaiting Stripe result.
verifiedIdentity successfully verified.
requires_inputVerification failed or incomplete; tenant action required.

This field is available on all mandate API responses.

Configuration

Ensure the following Stripe Identity events are enabled in your Stripe webhook configuration (Stripe Dashboard → Developers → Webhooks):

  • identity.verification_session.verified
  • identity.verification_session.requires_input

The webhook endpoint must be reachable by Stripe and the Stripe webhook signing secret must be configured in the service environment.

Related