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

# Pledge Webhooks

> Signed deliveries for every collateral lock, change, release and enforcement on a lending market

This page is for the party that receives pledge events, most often a register provider. After reading it you can create a webhook, verify its deliveries and rely on their order.

A pledge webhook sends your server one signed `POST` for every change to a pledge on the lending markets your instance can read. It carries what a register entry needs: the holder, the pledgee, the amount, the transaction and whether the pledge still stands. A register provider enters and releases pledges from these deliveries without polling [List Pledges](https://docs.trusset.org/endpoints/asset-register/list-pledges.md). The register entry stays the register provider's own act: a delivery reports the chain, and no webhook writes to a register.

Deployers, lenders of record and register providers use the same webhooks. Each receives the events of the markets its own instance can read.

## Create a webhook

Webhooks are created and managed in the Issuer Portal, on the Webhooks page of the instance. No API key endpoint creates one.

**1. Open Create Webhook**

Choose **Pledge recording** as the source of events.

**2. Enter the endpoint**

An `https` URL on a public host, without credentials in the URL. Redirects are not followed.

**3. Choose events and markets**

All seven events and all markets by default. A webhook set to all markets also covers markets the instance imports or deploys later. A webhook that names markets takes at most 50 of them.

**4. Save the signing secret**

The secret is shown once, when the webhook is created. Store it where your receiver can read it.

An instance holds at most 10 pledge webhooks. The webhook's details list the deliveries, newest first, with their status and offer a test delivery, a replay per delivery, a new signing secret, a pause switch and deletion.

## Which markets a webhook covers

| Instance | Markets |
| - | - |
| The deployer of a market | Its own markets |
| The lender of record | The markets it took |
| An asset register | The markets it [imported](https://docs.trusset.org/endpoints/asset-register/import-market.md) |

A register stops receiving a market's events when it declines the market, and when the deployer clears or replaces the register for the token.

## Events

| `type` | Sent when | Extra fields in `data` |
| - | - | - |
| `pledge.created` | A loan opened, or collateral was added under a new reference, and the adapter locked it in favour of the pledgee | |
| `pledge.increased` | Collateral was added to an existing pledge | |
| `pledge.decreased` | Part of the collateral was returned to the holder | |
| `pledge.released` | The pledge ended and the remaining collateral was released to the holder | `shortfallBorne`, only when the adapter returned less than the pledge recorded |
| `pledge.enforced` | Collateral was seized in a liquidation | `to`, the recipient. `final`, `true` when the seizure took the last of the pledge |
| `pledge.split` | Part of a pledge moved to a new reference with the same holder and pledgee. The event describes the new pledge | `fromRef`, `toRef`, `parentCurrentAmount` |
| `pledge.shortfall` | A freeze market asked the token to unfreeze more than was still frozen for the holder | `requested`, `unfrozen` |

For a register, `pledge.created` opens an entry and `pledge.released` takes it off. `pledge.enforced` with `final: true` means the pledge was realized. A `pledge.enforced` with `final: false` is a partial seizure, and the pledge stands for `currentAmount`.

In a `CUSTODY` market the token moves to the adapter, which is a transfer for security and not a pledge. The events are sent all the same, with `collateralMode: CUSTODY`, so a register that records pledges can skip them. See [Collateral mode changes what to record](https://docs.trusset.org/endpoints/asset-register/introduction.md#collateral-mode-changes-what-to-record).

## Payload

**id** `string`

The delivery ID. It stays the same across retries of one delivery. A replay gets a new one.

**type** `string`

One of the seven events, or `test` for a test delivery.

**webhookId** `string`

The webhook this delivery belongs to.

**instanceId** `string`

The instance that owns the webhook.

**idempotencyKey** `string`

One key per chain log and event type. Store it and skip a key you have already processed.

**emittedAt** `string`

When the event was queued, ISO 8601. The chain time is `data.transaction.at`.

**data** `object`

**network** `string`

The network of the market, for example `ETHEREUM`.

**environment** `string`

`PRODUCTION` or `DEVELOPMENT`.

**chainId** `integer`

The chain ID, or `null` when it could not be resolved.

**marketAddress** `string`

The lending market, lowercased.

**adapterAddress** `string`

The collateral adapter that emitted the log.

**tokenAddress** `string`

The collateral token.

**collateralMode** `string`

`FREEZE` or `CUSTODY`.

**token** `object`

`name`, `symbol`, `isin` and `decimals` of the collateral token as the market records them. Any of them can be `null`, and so can the object.

**ref** `string`

The adapter's reference for the lock, as 32 bytes. The same `ref` identifies the pledge on [List Pledges](https://docs.trusset.org/endpoints/asset-register/list-pledges.md).

**holder** `string`

The wallet whose collateral is locked.

**pledgee** `string`

The collateral agent named on the lock. `null` when the adapter records no pledgee.

**pledgeeUnavailable** `boolean`

`true` when `pledgee` is `null` because the adapter does not record one.

**amount** `string`

The amount this event moved, in the token's base units. On `pledge.shortfall` it is the part the token could not release: the amount requested less the amount unfrozen.

**currentAmount** `string`

What is still locked under `ref` after this event, in base units.

**active** `boolean`

`true` while the pledge has not ended and `currentAmount` is above zero.

**loanId** `string`

The loan the lock was created for, when exactly one loan of the market is recorded for the locking transaction. `null` otherwise.

**transaction** `object`

`hash`, `logIndex`, `block` and `at` of the log behind this event. `at` is the block time, ISO 8601.

**pledge** `object`

The pledge after this event: `ref`, `holder`, `pledgee`, `pledgeeUnavailable`, `amount` (everything ever locked under the reference), `currentAmount`, `active`, `lockedAt` and `endedAt`, as on [List Pledges](https://docs.trusset.org/endpoints/asset-register/list-pledges.md#response-fields).

Amounts are integer strings in the collateral token's base units, exactly as the adapter emitted them. Divide by ten to the power of `token.decimals` before a figure goes into a register entry.

```json pledge.created theme={null}
{
  "id": "5a1c0f0e-7d0b-4a55-9d0a-3d2b1f6f0c11",
  "type": "pledge.created",
  "webhookId": "cmwm4q1x70005l80e9s2k6b3c",
  "instanceId": "cmwk2r8v10003l80f4t6h9d2e",
  "idempotencyKey": "ethereum:production:0x9c4e2f7a1b3d5e6f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f7:14:pledge.created",
  "emittedAt": "2026-11-18T12:04:31.000Z",
  "data": {
    "network": "ETHEREUM",
    "environment": "PRODUCTION",
    "chainId": 1,
    "marketAddress": "0x70a0e25c7b768b87e658348b3b577678a173e038",
    "adapterAddress": "0x5c1d8e3f0a2b47c6913d0e8a7f24b6c5d9031e7a",
    "tokenAddress": "0x39478e924930d7fed1fa3803ecf9b0ddc08ce512",
    "collateralMode": "FREEZE",
    "token": { "name": "ACME Senior Bond 2030", "symbol": "ACME30", "isin": "DE000A3E5XK7", "decimals": 18 },
    "ref": "0x3f2a9c1d5b7e8a40c6d1f2b3a4958677e0d1c2b3a4f5e6d7c8b9a0f1e2d3c4b5",
    "holder": "0x8ba1f109551bd432803012645ac136ddd64dba72",
    "pledgee": "0x8b17e4d90c3a25f6e1d09b7c4a3f52e86d1c0b94",
    "pledgeeUnavailable": false,
    "amount": "1000000000000000000000",
    "currentAmount": "1000000000000000000000",
    "active": true,
    "loanId": "42",
    "transaction": {
      "hash": "0x9c4e2f7a1b3d5e6f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f7",
      "logIndex": 14,
      "block": 23891204,
      "at": "2026-11-18T12:03:11.000Z"
    },
    "pledge": {
      "ref": "0x3f2a9c1d5b7e8a40c6d1f2b3a4958677e0d1c2b3a4f5e6d7c8b9a0f1e2d3c4b5",
      "holder": "0x8ba1f109551bd432803012645ac136ddd64dba72",
      "pledgee": "0x8b17e4d90c3a25f6e1d09b7c4a3f52e86d1c0b94",
      "pledgeeUnavailable": false,
      "amount": "1000000000000000000000",
      "currentAmount": "1000000000000000000000",
      "active": true,
      "lockedAt": {
        "block": 23891204,
        "txHash": "0x9c4e2f7a1b3d5e6f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f7",
        "logIndex": 14,
        "at": "2026-11-18T12:03:11.000Z"
      },
      "endedAt": null
    }
  }
}
```

A test delivery carries `type: test` and `data.message`, and no `idempotencyKey`. A replay repeats the original payload with a new `id` and `emittedAt`, plus `replayed: true` and `replayOf` naming the delivery it repeats.

## Headers

| Header | Value |
| - | - |
| `x-webhook-signature` | HMAC-SHA256, hex, keyed with the signing secret exactly as shown, over the `x-webhook-timestamp` value, a dot and the raw body |
| `x-webhook-timestamp` | Unix seconds when the attempt is sent. Each retry carries a fresh one, and a fresh signature |
| `x-trusset-event` | The event `type` |
| `x-trusset-webhook-id` | The webhook |
| `x-trusset-delivery-id` | The delivery `id`. The same across retries |
| `x-trusset-idempotency-key` | The payload's `idempotencyKey`. A replay carries the key of the delivery it repeats. Absent on a test delivery |
| `user-agent` | `Trusset-Pledge-Webhook/1.0` |

## Verify a delivery

Compute the signature over the body bytes as they arrived, before any JSON parsing, and compare in constant time. Refuse a timestamp that is more than a few minutes off.

```typescript theme={null}
import { createHmac, timingSafeEqual } from 'node:crypto'

function isFromTrusset(rawBody: string, timestamp: string, signature: string, secret: string): boolean {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest()
  const received = Buffer.from(signature, 'hex')
  return received.length === expected.length && timingSafeEqual(received, expected)
}
```

The SDK does the same with [`readPledgeWebhook`](https://docs.trusset.org/sdk/asset-registers/webhooks).

Rotating the secret in the Issuer Portal stops the previous secret at once, with no overlap. Every attempt sent afterwards is signed with the new secret, including retries of deliveries queued earlier.

## Delivery, retries and order

Answer with any `2xx` within 10 seconds to accept a delivery. Do the work after you answered.

| Your answer | What happens |
| - | - |
| `2xx` | Delivered |
| `408`, `425`, `429`, any `5xx`, no answer in 10 seconds, or a connection error | Retried |
| Any other `4xx`, or a redirect | Failed at once, without a retry. The queue moves on to the next event |

A delivery gets up to 10 attempts over about 24 hours. The waits between them are 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 8 hours and 8 hours.

**Order.** The events of one market leave in chain order, by block and log position. Each market is read on its own, so there is no single order across the markets of one webhook. While a delivery waits for its retry, the later events of the same webhook wait behind it. Once it is delivered, or marked failed, the queue moves on. A replay is sent at once and holds nothing back. On a paused webhook it waits, and it is sent first when the webhook is switched back on.

**Suspended accounts.** While an account is suspended, its webhooks keep collecting events and send nothing. The queue is sent in order once the account is restored, as far as the 30-day retention reaches.

**Access.** A delivery is sent only while the webhook's instance still reads the market of the event. When an issuer removes or replaces a register, or the market leaves the instance, the deliveries still queued for that market are not sent. They show as failed with the reason `Not sent: this instance no longer reads the market of this event`, they do not count against the endpoint, and their content is no longer shown. A replay of such a delivery is refused with `403 MARKET_NOT_READABLE` for as long as the instance does not read the market. Once it reads the market again, for example after a register imports it again, the content is shown again and the replay goes out. The webhook's details in the Issuer Portal switch Replay off on these deliveries and say so. An account that is no longer approved as a register reads none of the markets it imported. They leave the market list of the Create Webhook page. A webhook that names one is refused with `403 REGISTER_NOT_APPROVED`.

**At least once.** A delivery can reach you more than once, for example when your `2xx` was lost on the way. Process each `idempotencyKey` once.

**Pausing.** When the tenth attempt of a delivery fails too, the webhook pauses itself and the delivery stays queued. Nothing is dropped: switch the webhook back on and the queue is sent in order, starting with that delivery. A webhook also pauses after 25 deliveries in a row that your endpoint refused without a retry. A paused webhook, whether paused by you or by itself, keeps collecting events.

**Retention.** Deliveries are kept for 30 days, delivered or not, and are then deleted. A failed delivery can be replayed from the webhook's details within that time.

**Starting point.** A webhook receives events that happened on chain after it was created. Read [List Pledges](https://docs.trusset.org/endpoints/asset-register/list-pledges.md) once for the pledges that already stand.

## When an event arrives

An event is sent once the block that holds its transaction is final on its network and the market's adapter logs have been read. The adapter logs are read up to the block the network reports as finalized, never up to the chain head. Finality normally takes 13 to 20 minutes on Ethereum and a few seconds on Polygon.

Take a transaction that an instance holding the market's record confirms through Trusset. The market is read about 45 seconds after that confirmation, then every two minutes until the finalized block has passed the confirmation, for at most 30 minutes. Every watched market is also read every ten minutes, which picks up transactions that did not pass through Trusset. Markets are read only while at least one active webhook covers them.

A read that fails is repeated, first after a minute and then at growing intervals up to 30 minutes. No event is lost by a failed read: the position in the chain moves only together with the events queued for it.

A webhook is the fast path, and [List Pledges](https://docs.trusset.org/endpoints/asset-register/list-pledges.md) stays the record to reconcile against. Its `index` fields say how far the chain has been read.

Every event comes from a final block, so a chain reorganisation does not remove its transaction afterwards. Confirmations are never counted in place of finality. While a network's finalized block cannot be read, no event is sent for that network. The events follow in chain order once it can be read. No later event withdraws an earlier one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.