Skip to main content
POST
Creates a hook on a lending market and returns 201 with the stored record. A hook is a rule Trusset evaluates off-chain. Creating one writes nothing on-chain, so there is nothing to sign or confirm.

​
When each hook type runs

A liquidation runs the active beforeLiquidation and afterLiquidation hooks of every instance that holds the market, once per liquidation, whichever confirm or sync records it first. A liquidation whose atomic sale has not been read back yet runs them once it is. A failing check records its result and does not stop the liquidation. A buy action runs only when the liquidation opened an auction. A monitor’s breach runs only inform actions, because a breach carries no auction to act on.

​
Signed deliveries

An inform action does not post inline. It queues a delivery that a worker sends and retries. A liquidation is announced to a hook at most once, and every attempt of a delivery carries the same id, so a retry is never a second event. Each attempt waits up to 15 seconds for an answer, and a 2xx answer delivers it. A 5xx, 408, 425 or 429 answer, a timeout or a connection failure is retried, up to eight attempts in all, after pauses of 10 seconds, 30 seconds, 1, 5, 15 and 30 minutes, then an hour. Any other answer, a redirect included, fails the delivery for good, as do a non-public host and a response body over 64 KB. Each delivery is a POST with these headers: The body carries id, event, hookId, marketId, emittedAt and timestamp, the last two both the time the event was queued. A liquidation adds loanId, marketLiquidationId, auctionId, collateralAmount, debtOwed, borrower, txHash and marketAddress. It also adds the outcome: realization (ATOMIC, ROUTER or VENUE), the atomic sale’s buyer, proceeds, surplus and reserve as Liquidate Loan returns them, and payee, the loan’s pay-to address. A field with no value reads null. A breach adds monitorHookId, monitorName, riskUri, checkedAt, breached with the failing fields and their values, and fields. The signing secret is returned once, as webhookSecret, when the hook is created. Store it then. Rotate Hook Secret issues a new one, and List Hook Deliveries lists the deliveries with their status, attempts and last error. A monitor is due once checkFrequency has passed since its last run, and a new monitor is due at once. The scheduler picks a new monitor up at its next wake-up, not at the moment of this call. Run it once with Execute Hook to see it evaluate.
riskUri and webhookUrl must be http or https URLs on a public host. A localhost, .local, .internal or .localhost hostname, or a private or reserved IP address, is refused at validation. Every outbound call resolves the hostname again and refuses it when any address it resolves to is not public. A monitor’s fetch follows at most four redirects, and each hop is checked the same way. A delivery follows none.

​
Path Parameters

​
string
required
The market’s record ID, as id on List Markets, not its contract address. See Market IDs.

​
Body Parameters

​
string
required
One of monitorRisk, beforeLiquidation or afterLiquidation.
​
string
Display name, 1 to 128 characters. Defaults to Risk Monitor, Pre-Liquidation Check or Post-Liquidation Action by hook type.
​
string
URL a monitor fetches on each run, at most 2048 characters. Required for monitorRisk.
​
array
Checks applied to the JSON body riskUri returns, at most 20. Required and non-empty for monitorRisk. Evaluation stops at the first field that fails.
​
number
Stored with the hook and returned on reads. No evaluation reads it.
​
string
Polling interval for monitorRisk. One of 1m, 5m, 15m, 30m, 1h, 6h, 12h, 24h. A hook without a checkFrequency is never scheduled and only runs when triggered manually.
​
array
Checks for beforeLiquidation, at most 10. They are evaluated against the liquidation’s data, or the loanData sent to Execute Hook, not against chain state. A check fails when its parameter is missing from that data. A liquidation’s data carries debtValue, the same figure as debtOwed in a delivery, and none of the other four parameters, so a check on any other parameter fails on every liquidation.
​
string
Required for afterLiquidation. buy prices a bid for the remaining collateral of the auction named in the run’s liquidationData, and returns the unsigned approval and bid steps; nothing is bid automatically. inform queues a signed delivery of the liquidation data to webhookUrl, as Signed deliveries describes.
​
string
Ceiling for a buy action, as a decimal string in the borrow asset per whole collateral token. When the auction’s current price is above it, the run returns no steps.
​
string
Destination of an inform action, at most 2048 characters. Required whenever actionType is inform.
​
object
Extra fields merged into the inform body. The fixed fields listed under Signed deliveries overwrite a key of the same name.
​
array
IDs of other hooks on the same market, at most 10. An afterLiquidation hook that lists any acts on a liquidation or an Execute Hook call only when every listed hook is active and its last counted run returned false. Otherwise the run records Trigger condition not met and does nothing. A breach of one listed monitor sends its riskBreach delivery without checking the others.

​
Response Fields

​
object
The new hook record, returned with HTTP 201. See List Hooks for each field. This call issues every hook a signing secret, so signed is true, and webhookSecret carries the secret, 64 hex characters, in this response only.

​
Error Codes