Your systems hear about each identity registration and role change as it reaches a block, signed, without asking the API on a timer. Polling means a scheduled job, empty responses and an interval that is either too slow for the back office or too heavy for the API. DALP 3.0 pushes signed events to the URLs you register and records every delivery attempt. Delivery is at least once, and after an outage you replay the deliveries that failed.
DALP signs each event, retries a failed delivery for up to three days and keeps every attempt on record
3.0 sends three event types: identity registration, role granted and role revoked. Each arrives once a block includes it, and a chain reorganisation that drops the block sends a retraction, so your records follow the on-chain outcome.
- Signing
- HMAC-SHA256, Standard Webhooks
- Live event types
- Identity, role granted, role revoked
- Retries
- Backoff for up to three days
- After 30 failures
- URL off until reactivated
Before and after
Before 3.0: an integration polled the API, handled empty responses, tuned an interval and built its own retry and deduplication. A role revoked on chain reached the back office only at the next poll, and a chain reorganisation that dropped a change went unnoticed.
With 3.0: DALP posts each subscribed event to your URL, signed, retries a failed delivery on a growing backoff for up to three days, and shows every attempt in the endpoint's delivery history.
DALP signs and posts each event, retries failures for up to three days, and switches a failing URL off until an operator reactivates it and replays.
Receive identity and role changes as they happen
3.0 sends three live event types: an identity registration, a role granted and a role revoked. Each arrives once a block includes the change, and a chain reorganisation that drops the block sends a retraction of the same event.
A developer chooses which event states an endpoint receives.
A Developer who is an owner or administrator of the organisation selects Create webhook endpoint, enters an “Endpoint URL”, which must start with https, and saves the signing secret the Console shows once. Under “Subscriptions” the Developer ticks *.provisional, the state these three events arrive in. When a Compliance officer registers an investor's identity, the back office receives the registration with the identity's address and the block it landed in, and opens the investor's account. When a member's role is revoked, the back office receives the role and the transaction that revoked it, looks up the member's wallet from that transaction and closes the member's access in its own systems. If a chain reorganisation drops either block, a retraction tells the back office to undo the step.
The event reference also lists transfer, issuance and freeze events, and 3.0 does not send them. Transfers, issuance, approvals and custody movements still need a read from the Platform API. A new endpoint subscribes to final, retracted and recalled events by default, and none of the three live events arrives in those states, so tick *.provisional when you create the endpoint.
Prove an event came from DALP before acting on it
Each delivery follows the Standard Webhooks scheme. It carries a webhook-id header equal to the event's evt_id, a webhook-timestamp header and a webhook-signature header holding an HMAC-SHA256 signature over the id, the timestamp and the raw body. The TypeScript SDK checks all of it in one call and returns the typed event, or a failure code of TIMESTAMP_SKEW, SECRET_MISMATCH or BODY_HASH_MISMATCH. It refuses a timestamp more than five minutes away, and DALP signs a delayed retry again so it arrives inside that window.
import { verifyWebhook } from "@settlemint/dalp-sdk";
export function handleDalpWebhook(rawBody: string, headers: Headers, secrets: string[]) {
// During a secret rotation, pass the new and the previous secret.
const result = verifyWebhook({ rawBody, headers, secret: secrets });
if (!result.ok) {
throw new Error(`Webhook verification failed: ${result.code}`);
}
// Delivery is at least once, so key processing on result.event.evt_id.
return result.event;
}When the Developer selects Rotate secret, the old and the new secret both stay valid for 24 hours, so receivers move to the new secret without missing an event. A forged or altered request fails verification and the handler refuses it. The signature proves DALP sent the event, and because delivery is at least once, the handler still keys its processing on evt_id.
Re-send failed deliveries after an outage
A 2xx response marks a delivery as delivered. A server error, a timeout, a 408 or a 429 is retried on a backoff that starts at about 30 seconds and grows with each attempt, for up to three days. Any other 4xx is not retried, because the same request would fail again. Each attempt appears in the delivery history with its status, failure class and HTTP status, and a single delivery can be retried by hand.
When the back office's receiver is down over a weekend, 30 failed deliveries in a row switch the URL off, and the “Circuit breaker” card shows “Disabled”.
On Monday the Developer fixes the receiver, selects “Send test event”, which still reaches a URL that is off, and confirms it verifies. The Developer then selects Reactivate manually, types the endpoint's name and replays the weekend's block range from the CLI or the Platform API, which re-sends the deliveries that failed before the URL switched off.
The delivery history shows which events failed and why, and a replay re-sends them with a fresh signature. Events that happen while a URL is off are not recorded for it, so a replay cannot bring them back, and the back office reads those changes from the Platform API.
Choose how much personal data leaves DALP
A new endpoint receives thin payloads: DALP strips the account's wallet address, the sender's address and the country code from each event before it signs it. An integration that needs the full subject state uses Switch to fat events, which asks the Developer to confirm every field that leaves DALP and to type the organisation's name before “Acknowledge, switch to fat events”.
Personal data leaves only after a named person at your organisation confirmed each field. The switch to fat payloads cannot be undone from the Console, so the receiving system falls under your data-protection controls from then on.
Upgrading
Nothing to do. Webhooks are an additional delivery channel, and integrations that poll the Platform API keep working as before.
Why it matters
- Banks: your core systems learn of each identity registration and role change from a signed message they verify before acting.
- Exchanges, CSDs and market infrastructures: A role grant or identity registration that a chain reorganisation drops reaches your systems as its own retraction event.
- Partners: an integration subscribes to the identity and role events it needs and replays the deliveries that failed during downtime.