# Webhook endpoints

Source: https://docs.settlemint.com/docs/developer-guides/api-integration/webhook-endpoints
Configure DALP webhook endpoints, delivery privacy, signing secrets, retries, and chain-of-custody proofs.



Webhook endpoints deliver selected DALP events to an external HTTPS URL. Use them when an integration needs pushed event delivery instead of polling token or account collections.

## Endpoint model [#endpoint-model]

Create endpoints with `POST /api/v2/webhooks`. The request includes:

| Field                   | Behaviour                                                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `url`                   | Required HTTPS target URL for delivery.                                                                                        |
| `displayName`           | Optional label, up to 200 characters.                                                                                          |
| `subscriptions`         | Event patterns to deliver. Defaults to `*.final`, `*.retracted`, and `*.recalled`.                                             |
| `defaultPayloadShape`   | Must be `thin` when creating an endpoint. Switch to `fat` later with a `PATCH` request and the required field acknowledgement. |
| `counterSignedReceipts` | Optional flag for endpoints that return signed delivery receipts.                                                              |

The create and rotate-secret responses reveal the signing secret once. Later reads return endpoint metadata and secret status, not the cleartext signing secret.

## Payload privacy [#payload-privacy]

DALP delivers thin payloads by default. Thin payloads omit configured personal-data fields for event types such as identity registration, access-control role changes, asset issuance, compliance freeze recalls, and token transfers.

Create the endpoint as `thin` first. Switching an endpoint to `fat` requires a later `PATCH /api/v2/webhooks/{id}` request with a `fatEventsAcknowledgment.fieldsAcknowledged` list that covers every additional field implied by the endpoint's subscriptions. DALP rejects the update when the acknowledgement does not match the subscription set.

## Delivery operations [#delivery-operations]

| Operation                                                                 | API route                                                    |
| ------------------------------------------------------------------------- | ------------------------------------------------------------ |
| List endpoints                                                            | `GET /api/v2/webhooks`                                       |
| Read endpoint metadata                                                    | `GET /api/v2/webhooks/{id}`                                  |
| Update URL, subscriptions, payload shape, receipt mode, or disabled state | `PATCH /api/v2/webhooks/{id}`                                |
| Disable an endpoint                                                       | `DELETE /api/v2/webhooks/{id}`                               |
| Enqueue a test event                                                      | `POST /api/v2/webhooks/{id}/test-events`                     |
| List delivery attempts                                                    | `GET /api/v2/webhooks/{id}/deliveries`                       |
| Read one delivery attempt                                                 | `GET /api/v2/webhooks/{id}/deliveries/{deliveryId}`          |
| Retry one delivery event                                                  | `POST /api/v2/webhooks/{id}/deliveries/{deliveryId}/retries` |
| Replay historical events                                                  | `POST /api/v2/webhooks/{id}/replays`                         |
| Recall an event                                                           | `POST /api/v2/webhooks/events/{evtId}/recall`                |
| Get chain-of-custody proof                                                | `GET /api/v2/webhooks/events/{evtId}/chain-of-custody`       |
| Rotate the signing secret                                                 | `POST /api/v2/webhooks/{id}/rotate-secret`                   |
| Revoke the previous signing secret                                        | `POST /api/v2/webhooks/{id}/revoke-previous-secret`          |
| Read delivery statistics                                                  | `GET /api/v2/webhooks/stats`                                 |

When updating an endpoint URL while deliveries are pending, pass `acknowledgePending=true` only when you intend DALP to retarget those queued attempts to the new URL.

Secret rotation keeps the previous signing secret valid for a 24-hour overlap. Revoke the previous secret after DALP has observed delivery under the new secret.

## Audit proof [#audit-proof]

DALP records delivery rows with the fields that were redacted during delivery preparation. It also records hop hashes for the prepared payload.

Chain-of-custody proofs return the event's hop hashes, Merkle root, and platform signature. Downstream systems can use that proof to verify what DALP delivered.

Related pages:

* [Operational integration patterns](/docs/developer-guides/api-integration/operational-integration-patterns)
* [Compliance providers](/docs/architecture/integrations/compliance-providers)
* [API reference](/docs/developer-guides/api-integration/api-reference)