> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didx.co.za/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive real-time notifications for credential issuance and verification events.

## Overview

Webhooks are HTTP callbacks that notify your application about events on the didx:me platform, removing the need to poll the API for status updates.

## Supported events

<Tabs>
  <Tab title="For Issuers">
    | Event                          | Description                                                         |
    | ------------------------------ | ------------------------------------------------------------------- |
    | `openid4vc.issuance.offered`   | Credential offer sent to user                                       |
    | `openid4vc.issuance.completed` | Credential in pending state in wallet (openid4vc session completed) |
    | `openid4vc.issuance.failed`    | Issuance attempt failed                                             |
    | `openid4vc.issuance.expired`   | Credential offer expired                                            |
    | `wallet.credential.accepted`   | User accepted credential in wallet                                  |
    | `wallet.credential.rejected`   | User rejected credential                                            |
  </Tab>

  <Tab title="For Verifiers">
    | Event                              | Description                             |
    | ---------------------------------- | --------------------------------------- |
    | `openid4vc.presentation.requested` | Presentation request created            |
    | `openid4vc.presentation.verified`  | User presented credentials successfully |
    | `openid4vc.presentation.failed`    | Verification attempt failed             |
    | `openid4vc.presentation.expired`   | Presentation request expired            |
    | `wallet.presentation.accepted`     | User accepted presentation request      |
    | `wallet.presentation.rejected`     | User rejected presentation request      |
  </Tab>
</Tabs>

## Registering a webhook endpoint

```bash theme={null}
curl -X POST "https://test.didxtech.com/me-creds/api/v1/endpoints" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/webhooks/credentials"
  }'
```

### Response (201 Created)

```json theme={null}
{
  "data": {
    "id": "du398r0fqd",
    "url": "https://your-domain.com/webhooks/credentials",
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:00:00.000Z"
  }
}
```

## Webhook payload structure

All webhook payloads include an `eventType` and a `payload` with a resource reference:

```json theme={null}
{
  "eventType": "openid4vc.issuance.completed",
  "payload": {
    "openId4VcIssuanceId": "cmfwfjxdq003js601bmgy9tva"
  }
}
```

## Technical requirements

Your webhook endpoint must:

* Accept **POST** requests.
* Use **HTTPS** exclusively.
* Respond promptly with a **2xx** status code.
* Handle **duplicate deliveries**. The platform may retry on failure.
* Be **idempotent**. Processing the same event twice should produce the same result.

## Local development

Use [ngrok](https://ngrok.com/) to expose your local server via a public HTTPS URL during development:

```bash theme={null}
ngrok http 3000
```

Register the resulting `https://` ngrok URL as your webhook endpoint. The platform retries failed deliveries automatically.