Skip to main content
Available from @trusset/sdk 0.8.0.
This page is for the party that receives pledge webhooks, most often a register provider. After reading it you can verify a delivery and act on each event once. A pledge webhook is created in the Issuer Portal, on the Webhooks page of the instance. The SDK does not create one. It gives you the two things a receiver needs: the signature check and the event types. Pledge Webhooks is the reference for the events, the headers and the retry schedule.

Verify and read a delivery

readPledgeWebhook checks the signature and returns the typed event. It throws a ValidationError when the signature does not match, when the timestamp is more than five minutes off, and when the body is not a Trusset event. Pass the body exactly as it arrived. A body that was parsed and serialized again no longer matches its signature, so read the raw bytes before any JSON middleware runs.
The sample keeps the processed keys in memory to stay short. Keep them in your database, because a delivery can arrive more than once and can arrive after a restart. Answer within 10 seconds. A 2xx accepts the delivery, a 5xx is retried, and a 400 fails it for good, which is the right answer to a signature that does not match. verifyWebhookSignature takes the same input and answers true or false without parsing the body. toleranceSeconds changes the five-minute window.

Act on an event

event.type narrows the event, so the fields of one event type are typed.
Amounts are integer strings in the collateral token’s base units. Divide by ten to the power of data.token.decimals before a figure goes into a register entry. In a CUSTODY market the token moved to the adapter, which is a transfer for security and not a pledge. data.collateralMode says which one an event describes.

What a receiver can rely on

  • An event is sent once the block that holds its transaction is final on its network, normally 13 to 20 minutes on Ethereum and a few seconds on Polygon.
  • The events of one market arrive in chain order. There is no single order across the markets of one webhook. While a delivery waits for its retry, later events of the same webhook wait behind it. Retries run for about 24 hours. After that the webhook pauses and keeps its queue.
  • A delivery can arrive more than once. idempotencyKey is the same every time. A replay from the Issuer Portal carries the same key and replayed: true.
  • A webhook receives events that happened after it was created. Read the pledges that already stand once with lending.pledges.list.
  • A webhook reports the chain. The register entry stays the register provider’s own act, and no delivery writes to a register.

Methods and endpoints