{
  "openapi": "3.1.0",
  "info": {
    "title": "Webhook Events",
    "description": "Event payloads delivered to your configured webhook endpoint.\n\nThese are **outgoing events** — DeepCredentials sends these to your webhook URL when an event occurs.\n\nEvery payload is **slim by design**: the `data` field carries only the resource id and the status values relevant to the event. To read claims, captured data, identification details, or any other field, fetch the resource via the documented GET endpoint with your API credential. This guarantees no captured data or PII leaves DeepCredentials over the webhook channel without an authenticated call.\n\nDelivery currently makes one synchronous attempt. A failed attempt is logged and discarded, so callbacks can be missed. Reconcile authoritative state through the documented authenticated B2B GET and list endpoints.\n\nSee the [Webhooks guide](../guides/webhooks.md) for setup, signature verification, and best practices.",
    "version": "1.2.0",
    "x-metadata": {
      "title": "Webhook Events",
      "description": "Event payloads delivered to your webhook endpoint"
    }
  },
  "tags": [
    {
      "name": "Webhook Events",
      "description": "Event payloads delivered to your webhook endpoint."
    }
  ],
  "security": [],
  "components": {
    "parameters": {
      "XWebhookEvent": {
        "name": "X-Webhook-Event",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Event type (same as `event` field in body)."
      },
      "XWebhookSignature": {
        "name": "X-Webhook-Signature",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "example": "a1b2c3d4e5f6..."
        },
        "description": "HMAC-SHA256 hex digest of the raw request body. Verifying is **recommended** — see the [Webhooks guide](../guides/webhooks.md#verifying-signatures)."
      },
      "XWebhookTimestamp": {
        "name": "X-Webhook-Timestamp",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "example": "1747393200"
        },
        "description": "Unix timestamp of the event."
      },
      "XWebhookSignaturePrevious": {
        "name": "X-Webhook-Signature-Previous",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "example": "d4e5f6a7b8c9..."
        },
        "description": "Present during the 24-hour secret rotation grace period — signature with the previous secret."
      }
    },
    "schemas": {
      "EnvelopeFields": {
        "type": "object",
        "properties": {
          "event": {
            "type": "string",
            "description": "Event type identifier (same value as the `X-Webhook-Event` header)."
          },
          "tenant_id": {
            "type": "string",
            "format": "uuid",
            "description": "Your organization ID.",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "When the event occurred (RFC 3339 UTC).",
            "example": "2026-05-16T10:00:00Z"
          }
        }
      },
      "VerificationCompletedData": {
        "type": "object",
        "required": [
          "session_id",
          "status"
        ],
        "properties": {
          "session_id": {
            "type": "string",
            "format": "uuid",
            "description": "ID of the verification session. Fetch the full snapshot (requested fields, captured `credential_subject_data`, error fields) via `GET /b2b/v1/verification-sessions/{sessionId}`.",
            "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
          },
          "status": {
            "type": "string",
            "enum": [
              "success",
              "failed",
              "expired"
            ],
            "description": "Terminal status reached.",
            "example": "success"
          },
          "credential_status": {
            "type": "string",
            "enum": [
              "valid",
              "suspended",
              "revoked"
            ],
            "description": "Token-status-list state of the presented credential. Present when a successful verification resolved credential status; evaluate it in addition to `status` when suspended or revoked credentials should not be accepted.",
            "example": "valid"
          }
        }
      },
      "IssuingStatusChangedData": {
        "type": "object",
        "required": [
          "offer_id",
          "status"
        ],
        "properties": {
          "offer_id": {
            "type": "string",
            "format": "uuid",
            "description": "ID of the credential offer. Fetch the full snapshot (claims, template, issued credential id, error fields) via `GET /b2b/v1/credential-offers/{offerId}`.",
            "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
          },
          "status": {
            "type": "string",
            "enum": [
              "issued",
              "failed",
              "expired"
            ],
            "description": "Terminal status the offer just reached.",
            "example": "issued"
          }
        }
      },
      "CredentialInvitationStatusChangedData": {
        "description": "Slim terminal invitation hint. `offer_id` is present only for `redeemed`.\n\nThis object never contains an invitation code, email address, claims, credential values, custom message, or redemption URL. Fetch the current code-free invitation metadata through `GET /b2b/v1/credential-invitations/{invitationId}`.",
        "oneOf": [
          {
            "title": "Redeemed invitation",
            "type": "object",
            "additionalProperties": false,
            "required": [
              "invitation_id",
              "status",
              "offer_id"
            ],
            "properties": {
              "invitation_id": {
                "type": "string",
                "format": "uuid",
                "description": "ID of the credential invitation."
              },
              "status": {
                "const": "redeemed",
                "description": "Terminal status the invitation reached."
              },
              "offer_id": {
                "type": "string",
                "format": "uuid",
                "description": "ID of the credential offer created by redemption."
              }
            }
          },
          {
            "title": "Expired invitation",
            "type": "object",
            "additionalProperties": false,
            "required": [
              "invitation_id",
              "status"
            ],
            "properties": {
              "invitation_id": {
                "type": "string",
                "format": "uuid",
                "description": "ID of the credential invitation."
              },
              "status": {
                "const": "expired",
                "description": "Terminal status the invitation reached."
              }
            }
          },
          {
            "title": "Revoked invitation",
            "type": "object",
            "additionalProperties": false,
            "required": [
              "invitation_id",
              "status"
            ],
            "properties": {
              "invitation_id": {
                "type": "string",
                "format": "uuid",
                "description": "ID of the credential invitation."
              },
              "status": {
                "const": "revoked",
                "description": "Terminal status the invitation reached."
              }
            }
          }
        ]
      },
      "CredentialStatusChangedData": {
        "type": "object",
        "required": [
          "credential_id",
          "status"
        ],
        "properties": {
          "credential_id": {
            "type": "string",
            "format": "uuid",
            "description": "ID of the issued credential. Fetch the full snapshot via `GET /b2b/v1/issued-credentials/{credentialId}`.",
            "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "suspended",
              "revoked"
            ],
            "description": "New credential status.",
            "example": "revoked"
          }
        }
      },
      "SelfServiceRequestData": {
        "type": "object",
        "required": [
          "request_id"
        ],
        "properties": {
          "request_id": {
            "type": "string",
            "format": "uuid",
            "description": "ID of the self-service request. Fetch the full snapshot (status, captured claims, extra fields, identification result, offer id, admin-claims schema) via `GET /b2b/v1/self-service/requests/{requestId}`.",
            "example": "8a3b1f2e-9c4d-4e5a-b1c2-d3e4f5a6b7c8"
          }
        }
      },
      "SwiyuConfigData": {
        "type": "object",
        "required": [
          "tenant_id",
          "environment",
          "action"
        ],
        "properties": {
          "tenant_id": {
            "type": "string",
            "format": "uuid",
            "description": "Your organization ID.",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "environment": {
            "type": "string",
            "enum": [
              "beta",
              "production"
            ],
            "description": "Environment whose swiyu integration changed.",
            "example": "beta"
          },
          "action": {
            "type": "string",
            "enum": [
              "configured",
              "deconfigured"
            ],
            "description": "Whether the integration was configured or removed.",
            "example": "configured"
          }
        }
      }
    }
  },
  "webhooks": {
    "verification.completed": {
      "post": {
        "summary": "Verification Completed",
        "operationId": "webhook:verification.completed",
        "description": "Delivered when a verification session reaches a terminal status (`success`, `failed`, or `expired`).\n\nFetch the full session snapshot — requested fields, captured `credential_subject_data`, error fields — via `GET /b2b/v1/verification-sessions/{sessionId}`.",
        "tags": [
          "Webhook Events"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/XWebhookEvent"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignature"
          },
          {
            "$ref": "#/components/parameters/XWebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignaturePrevious"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EnvelopeFields"
                  },
                  {
                    "type": "object",
                    "required": [
                      "event",
                      "tenant_id",
                      "timestamp",
                      "data"
                    ],
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/VerificationCompletedData"
                      }
                    }
                  }
                ]
              },
              "example": {
                "event": "verification.completed",
                "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
                "timestamp": "2026-03-29T12:00:00Z",
                "data": {
                  "session_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
                  "status": "success",
                  "credential_status": "valid"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event acknowledged — return any `2xx` status to confirm receipt."
          }
        }
      }
    },
    "issuing.status_changed": {
      "post": {
        "summary": "Issuing Status Changed",
        "operationId": "webhook:issuing.status_changed",
        "description": "Delivered when a credential offer reaches a terminal status (`issued`, `failed`, or `expired`).\n\nFetch the full offer snapshot — claims, template, issued credential id, error fields — via `GET /b2b/v1/credential-offers/{offerId}`.",
        "tags": [
          "Webhook Events"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/XWebhookEvent"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignature"
          },
          {
            "$ref": "#/components/parameters/XWebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignaturePrevious"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EnvelopeFields"
                  },
                  {
                    "type": "object",
                    "required": [
                      "event",
                      "tenant_id",
                      "timestamp",
                      "data"
                    ],
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/IssuingStatusChangedData"
                      }
                    }
                  }
                ]
              },
              "example": {
                "event": "issuing.status_changed",
                "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
                "timestamp": "2026-04-02T12:01:00Z",
                "data": {
                  "offer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
                  "status": "issued"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event acknowledged — return any `2xx` status to confirm receipt."
          }
        }
      }
    },
    "credential_invitation.status_changed": {
      "post": {
        "summary": "Credential Invitation Status Changed",
        "operationId": "webhook:credential_invitation.status_changed",
        "description": "Delivered when a credential invitation reaches a terminal status: `redeemed`, `expired`, or `revoked`. Creation and code rotation do not emit this event.\n\nThis event is opt-in. Existing webhook configurations must enable it in the portal. On `redeemed`, `offer_id` identifies the new credential offer and starts the normal offer lifecycle. Fetch the authoritative invitation metadata through `GET /b2b/v1/credential-invitations/{invitationId}`.",
        "tags": [
          "Webhook Events"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/XWebhookEvent"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignature"
          },
          {
            "$ref": "#/components/parameters/XWebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignaturePrevious"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EnvelopeFields"
                  },
                  {
                    "type": "object",
                    "required": [
                      "event",
                      "tenant_id",
                      "timestamp",
                      "data"
                    ],
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/CredentialInvitationStatusChangedData"
                      }
                    }
                  }
                ]
              },
              "examples": {
                "redeemed": {
                  "summary": "Invitation redeemed into an offer",
                  "value": {
                    "event": "credential_invitation.status_changed",
                    "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
                    "timestamp": "2026-08-18T10:03:00Z",
                    "data": {
                      "invitation_id": "305ac8b8-299a-4e63-a969-405840e67772",
                      "status": "redeemed",
                      "offer_id": "4638c446-a36d-4993-92f2-ea760fbad19e"
                    }
                  }
                },
                "expired": {
                  "summary": "Invitation expired without redemption",
                  "value": {
                    "event": "credential_invitation.status_changed",
                    "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
                    "timestamp": "2026-08-19T10:00:00Z",
                    "data": {
                      "invitation_id": "305ac8b8-299a-4e63-a969-405840e67772",
                      "status": "expired"
                    }
                  }
                },
                "revoked": {
                  "summary": "Invitation revoked by the organization",
                  "value": {
                    "event": "credential_invitation.status_changed",
                    "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
                    "timestamp": "2026-08-18T10:02:00Z",
                    "data": {
                      "invitation_id": "305ac8b8-299a-4e63-a969-405840e67772",
                      "status": "revoked"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event acknowledged — return any `2xx` status to confirm receipt."
          }
        }
      }
    },
    "credential.status_changed": {
      "post": {
        "summary": "Credential Status Changed",
        "operationId": "webhook:credential.status_changed",
        "description": "Delivered when an issued credential's status changes (`revoked`, `suspended`, or `active` for a reactivation).\n\nFetch the full credential snapshot via `GET /b2b/v1/issued-credentials/{credentialId}`.",
        "tags": [
          "Webhook Events"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/XWebhookEvent"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignature"
          },
          {
            "$ref": "#/components/parameters/XWebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignaturePrevious"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EnvelopeFields"
                  },
                  {
                    "type": "object",
                    "required": [
                      "event",
                      "tenant_id",
                      "timestamp",
                      "data"
                    ],
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/CredentialStatusChangedData"
                      }
                    }
                  }
                ]
              },
              "example": {
                "event": "credential.status_changed",
                "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
                "timestamp": "2026-04-02T14:00:00Z",
                "data": {
                  "credential_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
                  "status": "revoked"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event acknowledged — return any `2xx` status to confirm receipt."
          }
        }
      }
    },
    "self_service.request.submitted": {
      "post": {
        "summary": "Self-Service Request Submitted",
        "operationId": "webhook:self_service.request.submitted",
        "description": "Delivered when an end-user finishes the self-service flow (filled the form + completed identification if required) and the request is ready for a decision.\n\n**Only fires for configs with `verification_mode: webhook`.** In `manual` mode the request is approved/rejected from the portal UI; in `automatic` mode it is auto-approved server-side and no submitted webhook is sent.\n\nAfter receiving this event, fetch the request via `GET /b2b/v1/self-service/requests/{requestId}` to inspect captured claims and the admin-claims schema, then POST your decision to `/b2b/v1/self-service/requests/{requestId}/decision`.",
        "tags": [
          "Webhook Events"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/XWebhookEvent"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignature"
          },
          {
            "$ref": "#/components/parameters/XWebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignaturePrevious"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EnvelopeFields"
                  },
                  {
                    "type": "object",
                    "required": [
                      "event",
                      "tenant_id",
                      "timestamp",
                      "data"
                    ],
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/SelfServiceRequestData"
                      }
                    }
                  }
                ]
              },
              "example": {
                "event": "self_service.request.submitted",
                "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
                "timestamp": "2026-05-16T10:00:00Z",
                "data": {
                  "request_id": "8a3b1f2e-9c4d-4e5a-b1c2-d3e4f5a6b7c8"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event acknowledged — return any `2xx` status to confirm receipt."
          }
        }
      }
    },
    "self_service.request.approved": {
      "post": {
        "summary": "Self-Service Request Approved",
        "operationId": "webhook:self_service.request.approved",
        "description": "Delivered when a self-service request has been approved — by a portal admin (`manual` mode), the tenant's `POST /decision` call (`webhook` mode), or automatically server-side (`automatic` mode).\n\nFires for **all verification modes** so the tenant has an audit trail of every decision. Fetch the resulting status, offer id, and merged claims via `GET /b2b/v1/self-service/requests/{requestId}`.",
        "tags": [
          "Webhook Events"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/XWebhookEvent"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignature"
          },
          {
            "$ref": "#/components/parameters/XWebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignaturePrevious"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EnvelopeFields"
                  },
                  {
                    "type": "object",
                    "required": [
                      "event",
                      "tenant_id",
                      "timestamp",
                      "data"
                    ],
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/SelfServiceRequestData"
                      }
                    }
                  }
                ]
              },
              "example": {
                "event": "self_service.request.approved",
                "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
                "timestamp": "2026-05-16T10:05:00Z",
                "data": {
                  "request_id": "8a3b1f2e-9c4d-4e5a-b1c2-d3e4f5a6b7c8"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event acknowledged — return any `2xx` status to confirm receipt."
          }
        }
      }
    },
    "self_service.request.rejected": {
      "post": {
        "summary": "Self-Service Request Rejected",
        "operationId": "webhook:self_service.request.rejected",
        "description": "Delivered when a self-service request has been rejected — by a portal admin (`manual` mode) or by the tenant's `POST /decision` call (`webhook` mode).\n\nFetch the rejection reason and the full request via `GET /b2b/v1/self-service/requests/{requestId}`.",
        "tags": [
          "Webhook Events"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/XWebhookEvent"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignature"
          },
          {
            "$ref": "#/components/parameters/XWebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignaturePrevious"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EnvelopeFields"
                  },
                  {
                    "type": "object",
                    "required": [
                      "event",
                      "tenant_id",
                      "timestamp",
                      "data"
                    ],
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/SelfServiceRequestData"
                      }
                    }
                  }
                ]
              },
              "example": {
                "event": "self_service.request.rejected",
                "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
                "timestamp": "2026-05-16T10:05:00Z",
                "data": {
                  "request_id": "8a3b1f2e-9c4d-4e5a-b1c2-d3e4f5a6b7c8"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event acknowledged — return any `2xx` status to confirm receipt."
          }
        }
      }
    },
    "self_service.request.credential_issued": {
      "post": {
        "summary": "Self-Service Request — Credential Issued",
        "operationId": "webhook:self_service.request.credential_issued",
        "description": "Delivered when the end-user's wallet has accepted the credential offer created from a self-service request — terminal success.\n\nFires for **all verification modes**. Fetch the full request (including `offer_id` and `completed_at`) via `GET /b2b/v1/self-service/requests/{requestId}`.",
        "tags": [
          "Webhook Events"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/XWebhookEvent"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignature"
          },
          {
            "$ref": "#/components/parameters/XWebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignaturePrevious"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EnvelopeFields"
                  },
                  {
                    "type": "object",
                    "required": [
                      "event",
                      "tenant_id",
                      "timestamp",
                      "data"
                    ],
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/SelfServiceRequestData"
                      }
                    }
                  }
                ]
              },
              "example": {
                "event": "self_service.request.credential_issued",
                "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
                "timestamp": "2026-05-16T10:10:00Z",
                "data": {
                  "request_id": "8a3b1f2e-9c4d-4e5a-b1c2-d3e4f5a6b7c8"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event acknowledged — return any `2xx` status to confirm receipt."
          }
        }
      }
    },
    "self_service.request.offer_expired": {
      "post": {
        "summary": "Self-Service Request — Offer Expired",
        "operationId": "webhook:self_service.request.offer_expired",
        "description": "Delivered when the live credential offer created from an approved self-service request expired before the end-user's wallet accepted it. Terminal — no further delivery for this request id. If the user still needs the credential, ask them to submit a new request.\n\nFires for **all verification modes**. Fetch the full request via `GET /b2b/v1/self-service/requests/{requestId}`.",
        "tags": [
          "Webhook Events"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/XWebhookEvent"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignature"
          },
          {
            "$ref": "#/components/parameters/XWebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignaturePrevious"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EnvelopeFields"
                  },
                  {
                    "type": "object",
                    "required": [
                      "event",
                      "tenant_id",
                      "timestamp",
                      "data"
                    ],
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/SelfServiceRequestData"
                      }
                    }
                  }
                ]
              },
              "example": {
                "event": "self_service.request.offer_expired",
                "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
                "timestamp": "2026-05-16T10:25:00Z",
                "data": {
                  "request_id": "8a3b1f2e-9c4d-4e5a-b1c2-d3e4f5a6b7c8"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event acknowledged — return any `2xx` status to confirm receipt."
          }
        }
      }
    },
    "self_service.request.failed": {
      "post": {
        "summary": "Self-Service Request — Failed",
        "operationId": "webhook:self_service.request.failed",
        "description": "Delivered when a self-service request reaches a non-recoverable failure state — typically the end-user's wallet rejected the credential after starting the OID4VCI exchange. Terminal — ask the user to update their wallet (the usual culprit) and submit a new request.\n\nFires for **all verification modes**. Fetch the full request via `GET /b2b/v1/self-service/requests/{requestId}`.",
        "tags": [
          "Webhook Events"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/XWebhookEvent"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignature"
          },
          {
            "$ref": "#/components/parameters/XWebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignaturePrevious"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EnvelopeFields"
                  },
                  {
                    "type": "object",
                    "required": [
                      "event",
                      "tenant_id",
                      "timestamp",
                      "data"
                    ],
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/SelfServiceRequestData"
                      }
                    }
                  }
                ]
              },
              "example": {
                "event": "self_service.request.failed",
                "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
                "timestamp": "2026-05-16T10:12:00Z",
                "data": {
                  "request_id": "8a3b1f2e-9c4d-4e5a-b1c2-d3e4f5a6b7c8"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event acknowledged — return any `2xx` status to confirm receipt."
          }
        }
      }
    },
    "swiyu.configured": {
      "post": {
        "summary": "Swiyu Integration Configured",
        "operationId": "webhook:swiyu.configured",
        "description": "Delivered when your organization's swiyu issuance/verification integration becomes active for an environment — the environment is ready to issue and verify credentials.\n\nThis is a **system event** about your environment's configuration, not a per-resource event. It is delivered to every configured webhook endpoint regardless of the per-event subscription grid.",
        "tags": [
          "Webhook Events"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/XWebhookEvent"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignature"
          },
          {
            "$ref": "#/components/parameters/XWebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignaturePrevious"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EnvelopeFields"
                  },
                  {
                    "type": "object",
                    "required": [
                      "event",
                      "tenant_id",
                      "timestamp",
                      "data"
                    ],
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/SwiyuConfigData"
                      }
                    }
                  }
                ]
              },
              "example": {
                "event": "swiyu.configured",
                "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
                "timestamp": "2026-05-16T09:00:00Z",
                "data": {
                  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
                  "environment": "beta",
                  "action": "configured"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event acknowledged — return any `2xx` status to confirm receipt."
          }
        }
      }
    },
    "swiyu.deconfigured": {
      "post": {
        "summary": "Swiyu Integration Removed",
        "operationId": "webhook:swiyu.deconfigured",
        "description": "Delivered when your organization's swiyu integration for an environment is removed — the environment can no longer issue or verify credentials until it is reconfigured.\n\nThis is a **system event** about your environment's configuration, not a per-resource event. It is delivered to every configured webhook endpoint regardless of the per-event subscription grid.",
        "tags": [
          "Webhook Events"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/XWebhookEvent"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignature"
          },
          {
            "$ref": "#/components/parameters/XWebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/XWebhookSignaturePrevious"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EnvelopeFields"
                  },
                  {
                    "type": "object",
                    "required": [
                      "event",
                      "tenant_id",
                      "timestamp",
                      "data"
                    ],
                    "properties": {
                      "data": {
                        "$ref": "#/components/schemas/SwiyuConfigData"
                      }
                    }
                  }
                ]
              },
              "example": {
                "event": "swiyu.deconfigured",
                "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
                "timestamp": "2026-05-16T09:00:00Z",
                "data": {
                  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
                  "environment": "beta",
                  "action": "deconfigured"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event acknowledged — return any `2xx` status to confirm receipt."
          }
        }
      }
    }
  }
}