Proven Webhook Documentation

Proven Webhook Documentation

Overview

Webhooks provide real-time notifications about events on Proven agents. They are delivered as HTTP POST requests to a configured endpoint.

Webhook Structure

Headers:

Header	Example Value	Description
Content-Type	application/json	Request content type
X-API-Key	24680AEIOUY	Authentication key
User-Agent	node-fetch/1.0	Client identifier
Content-Length	1584	Request body size in bytes
Accept-Encoding	gzip,deflate	Supported compression methods

Payload Format:

{
  "event": "event_type",
  "webhook": {
// Event-specific data
  }
}

Webhook Events

Description: This is triggered when a connection is fully established.

Event Type: connection:completed

Payload Example:

{
  "event": "connection:completed",
  "webhook": {
    "connection_id": "13eeacd4-0c4e-495e-81cc-d66c6eeb8545",
    "invitation_key": "2St9MAnpToLcnUxhfskNBYgNxzS4vzAy42kSWPF8AY9e",
    "invitation_msg_id": "7f7392eb-a334-43c9-bdb0-b1a109de1f91",
    "contact_id": null,
    "purpose": "invitation purpose",
    "wallet_id": "f161e7a3-9a88-4f2c-a988-cc9cf3fbea2f",
    "discovered_features": [
      {
        "pid": "https://didcomm.org/present-proof/2.0",
        "roles": [
          "prover",
          "verifier"
        ]
      },
      // ... additional protocol features
    ]
  }
}

AnonCred/JSON-LD Credential Issued

Description: This is triggered when a credential is successfully issued.

Event Type: credentials:done

Payload Example:

{
  "event": "credentials:done",
  "webhook": {
    "state": "done",
    "connection_id": "13eeacd4-0c4e-495e-81cc-d66c6eeb8545",
    "cred_ex_id": "794657e2-187e-4642-b5f2-77dd27138a49",
    "thread_id": "d92933ef-74d8-4e53-9d4a-6526feb991c5",
    "wallet_id": "f161e7a3-9a88-4f2c-a988-cc9cf3fbea2f",
    "role": "issuer",
    "initiator": "self",
    "created_at": "2025-03-13T22:14:41.138935Z",
    "updated_at": "2025-03-13T22:15:02.479961Z",
    "credential_id": null
  }
}

AnonCred/JSON-LD Presentation Verified

Description: This is triggered when a presentation is successfully verified.

Event Type: presentation:verified

Payload Example:

{
  "event": "presentation:verified",
  "webhook": {
    "state": "done",
    "connection_id": "13eeacd4-0c4e-495e-81cc-d66c6eeb8545",
    "pres_ex_id": "7ec0d756-58e8-402d-9688-2dc4cd48cf17",
    "thread_id": "00b7fe05-79a1-44a8-91bd-8f0fe47f249d",
    "wallet_id": "f161e7a3-9a88-4f2c-a988-cc9cf3fbea2f",
    "role": "verifier",
    "initiator": "self",
    "verified": "true",
    "created_at": "2025-03-13T22:15:04.202161Z",
    "updated_at": "2025-03-13T22:15:14.343137Z"
  }
}

OID4VC Issued

Description: This is triggered when a credential is successfully issued.

Event Type: oid4vc-credential:issued

Payload Example:

{
  event: 'oid4vc-credential:issued',
  webhook: {
    exchange_id: 'd3e347d2-e6df-45cf-bb02-27a929311260',
    supported_cred_id: '413f8b60-6587-40bd-95ee-58797c3d6543',
    credential_subject: {
      given_name: 'Alice',
      family_name: 'Smith',
      something_nested: { key1: { key2: { key3: 'something nested' } } },
      source_document_type: 'id_card',
      age_equal_or_over: {
        '12': true,
        '14': true,
        '16': true,
        '18': true,
        '21': true,
        '65': false
      }
    },
    verification_method: 'did:sov:NQ6iZJjvwdMzedXHzxX1vf#key-1',
    state: 'issued',
    issuer_id: 'did:sov:NQ6iZJjvwdMzedXHzxX1vf',
    code: 'Naqioo54ryqIAbNbfcWYTg',
    token: 'eyJ0eXAiOiAiSldUIiwgImtpZCI6ICJkaWQ6c292Ok5RNmlaSmp2d2RNemVkWEh6eFgxdmYja2V5LTEiLCAiYWxnIjogIkVkRFNBIn0.eyJpZCI6ICJkM2UzNDdkMi1lNmRmLTQ1Y2YtYmIwMi0yN2E5MjkzMTEyNjAiLCAiZXhwIjogMTc0MjA3NDM2Mn0.JffFZI7MgkWyZDLckUpY75flch4HdMqIHnUh1suHAoOOjjQ0OD9nNCNChNl5uCHrWZnrxsT9nQl-npZGqGDIDA'
  }
}

OID4VCP Verified

Description: This is triggered when a presentation is successfully verified.

Event Type: presentation:verified

Payload Example:

{
  event: 'oid4vc-presentation:verified',
  webhook: {
    pres_def_id: 'b1c679d4-6edb-4d22-ba65-553dd7f6ef0a',
    presentation_id: '28e70110-57b4-494e-b13b-aa728eac88c4',
    request_id: '00f70502-0618-4b9e-af9f-e8af07f6edcd',
    matched_credentials: {
      'ID Card': {
        something_nested: { key1: { key2: { key3: 'something nested' } } },
        source_document_type: 'id_card',
        age_equal_or_over: {},
        sub: 'did:jwk:eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6IkFlRzUyZk9oVnliN2VsYWtxVEFwc25ab2RCMkhuRGQ0YzE0d2NtRTRsOWMiLCJ5IjoiLW5VTmljSi0yUVV0UTNaVjBSc0NMMzNEVmVtcFNNUXBheG04VWQ0ZXlSayJ9',
        cnf: {
          kid: 'did:jwk:eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6IkFlRzUyZk9oVnliN2VsYWtxVEFwc25ab2RCMkhuRGQ0YzE0d2NtRTRsOWMiLCJ5IjoiLW5VTmljSi0yUVV0UTNaVjBSc0NMMzNEVmVtcFNNUXBheG04VWQ0ZXlSayJ9#0'
        },
        vct: 'testCard',
        iss: 'did:sov:NQ6iZJjvwdMzedXHzxX1vf',
        iat: 1741987962,
        given_name: 'Alice',
        family_name: 'Smith'
      }
    },
    state: 'presentation-valid'
  }
}

Basic Message Received

Description: This is triggered when a presentation is successfully verified.

Event Type: webhook:basic-message

Payload Example:

{
  event: 'basic-message:received',
  webhook: {
    connection_id: '9775b821-be93-4980-94d9-e3deaf6698d3',
    message_id: '4a977851-e5be-40fd-b3d6-3e01ae249c77',
    content: 'New',
    state: 'received',
    sent_time: '2025-03-14T02:28:57.839Z',
    locale: 'en',
    wallet_id: '122b480d-2813-42b5-9146-2d359a5dd807'
  }
}

Authentication

• Header: x-api-key (optional)

• Example: x-api-key: 24680AEIOUY

Security Considerations

• Use the x-api-key header (recommended).

• Use HTTPS for all endpoints.

• Verify request signatures if available.

• Validate JSON schema of incoming payloads.