Skip to Content
DocsCredsEzrah Creds Webhook

Ezrah Webhook Events for Partners

When integrated with Ezrah’s credential system, partner endpoints may receive POST requests related to credential presentations. These events help partners verify, log, or process user interactions involving credentials.

Requirements for Partner Endpoints

  • Accept POST requests.
  • Handle the following event types (sent in the JSON body):
    • event – the type of presentation.
    • data – the credential or presentation payload.
  • Must verify the presence of the header X-EZH-REQ-KEY.

Webhook Event Types

Here are the three event types Ezrah may send:

W3C Presentation - w3c_presentation

A Verifiable Presentation (VP) containing one or more W3C Verifiable Credentials.

Example Payload:

event.json
{
  "event": "w3c_presentation",
  verification_model: {
    id: string,
    verification_title: string,
    title: string,
    purpose: string,
    verification_link: string,
    model_type: string,
    client_id: string
  },
  "data": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1"
    ],
    "type": ["VerifiablePresentation"],
    "verifiableCredential": [
      {
        "@context": ["https://www.w3.org/2018/credentials/v1"],
        "type": ["VerifiableCredential", "KYC"],
        "issuer": "did:ezrah:abc...",
        "credentialSubject": {
          "id": "did:ezrah:123",
          "name": "Alice"
        },
        "proof": { ... }
      }
    ],
    "holder": "did:ezrah:xyz",
    "proof": { ... }
  }
}

SD-JWT Presentation sd_jwt_presentation

A presentation using Selective Disclosure JWT (SD-JWT) format, typically used for compact, privacy-respecting claims.

Example Payload:

event.json
{
  "event": "sd_jwt_presentation",
  verification_model: {
    id: string,
    verification_title: string,
    title: string,
    purpose: string,
    verification_link: string,
    model_type: string,
    client_id: string
  },
  "data": {
    "status" "VERIFIED",
    "issuer": "did:ezrah:abc...",
    "subject": "did:ezrah:123",
    "original_jwt": "eyJhbGciOi..."
  }
}

Auth Presentation - auth_credential_presentation

A lightweight presentation used during authentication flows (e.g., logging into a partner system using a verifiable credential).

Example Payload:

event.json
{
  "event": "auth_credential_presentation",
  verification_model: {
    id: string,
    verification_title: string,
    title: string,
    purpose: string,
    verification_link: string,
    model_type: string,
    client_id: string
  },
  "data": {
    "credential_type": "EzrahAccessToken",
    "issued_by": "did:ezrah:issuer123",
    "subject_id": "did:ezrah:456",
    "issued_at": "2025-06-08T12:00:00Z",
    "expires_at": "2025-06-09T12:00:00Z"
  }
}

Security: Request Headers

Every webhook request includes:

HeaderDescription
X-EZH-REQ-KEYPartner-specific secret to validate authenticity of the request.

Partners must validate this header matches the agreed request_key.

Retry & Delivery Notes

Webhook requests are retried by 70 attempts based on an exponential decaying timeline. i.e it retries lesser and lesser over a long period of time.

Testing Suggestions for Partners

  • Set up a simple endpoint to log all incoming POST requests.
  • Validate the X-EZH-REQ-KEY.
  • Handle the three possible event values.
  • Deserialize data based on event type.
Last updated on
Ezrah Creds SDKIntroduction to Decentralized Identity