> For the complete documentation index, see [llms.txt](https://docs.indicio.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.indicio.tech/developer/indicio-proven-r/how-to-guides/proven-webhook-documentation.md).

# 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.

<figure><img src="https://3134937471-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fgm8V7K7elYyNNEcnVUT8%2Fuploads%2Fmw6uOxjlYFQRpaXXQPce%2FIndicio%20Copyright%20Image%20Transparent%20(Wide).png?alt=media&amp;token=af3f2ee9-7110-4ff9-8abd-6f45e18fe703" alt=""><figcaption></figcaption></figure>