A webhook endpoint is the HTTPS address that receives DALP events. It receives an event when one of its subscription patterns matches the event name. A pattern is an exact name, *, a name prefix ending in .*, or a state pattern such as *.final.
Pattern grammar
A pattern has one of four forms. For a new event, the platform matches it against the event name only. An event name has three parts separated by dots, for example token.transfer.final. Many names end in a lifecycle state. Some end in another word, such as funding..
Syntax rules
- A segment contains lowercase letters, digits, and hyphens. A hyphen sits between two letters or digits.
- Dots separate segments, and no segment is empty.
*is a complete segment. It stands alone, comes first in a state pattern, or comes last in a name prefix.- A name prefix has one or more segments before
.*. - An exact name has exactly three segments.
The patterns token.*.final and Token.transfer.* break these rules. The platform answers a request that contains such a pattern with status 400 and the error REQUEST_INVALID, id DALP-14261.
Validation
A pattern with valid syntax must also pass the registry rules. The platform applies them on POST /api/, and on PATCH /api/ when the body supplies subscriptions. A pattern or list that fails answers status 400 with the error WEBHOOK_, id DALP-0534. The error is not retryable. Change the list and send the request again. The Platform API error reference lists both errors.
The state in a state pattern must be one of pending, provisional, final, retracted, or recalled. A name prefix or an exact name must match a registered event. The retired custody ledger events are no longer registered (the SDK changelog names each removed event). An endpoint that already holds one keeps working, but saving a list that still names one is rejected with WEBHOOK_ until the name is dropped. The pattern *.recalled is accepted. It delivers only a recalled event that DALP 3.1 stored and a Replay resends. The reserved name compliance. is also accepted as an exact subscription, although no action sends it. The other reserved names, token.transfer.pending and settlement., are rejected as exact names.
Retraction subscriptions
A retraction is an event whose name ends in .retracted. It withdraws an earlier event, and the retraction supersedes that event. The platform rejects a list when one of its patterns matches a retraction and no pattern in the list matches the event that the retraction supersedes. The rule applies when the name of the superseded event ends in .pending, .provisional, or .final.
For a chain reorganisation correction, the platform checks whether it recorded a successful delivery of the removed chain observation. The endpoint's subscription patterns do not decide whether the platform generates that automatic correction. Receiver-side processing alone is not a recorded delivery. Your receiver must handle these corrections. The retraction rules cover lost acknowledgements.
Worked examples
Bank rail endpoints select bank-rail.credit.* and bank-rail.cash-out.* explicitly. The defaults skip these milestone names, including bank-, whose envelope state is final. A *.recalled pattern matches that event's name too, but matching a suffix never changes its envelope state.
Default subscriptions
A new endpoint receives events that match three state patterns: *.provisional, *.final, and *.retracted. The platform applies them when the create request omits subscriptions. The Console create form starts with the same three patterns selected.
State patterns match the last part of the event name. They never read the lifecycle_state field of the envelope. The defaults therefore skip an event whose name ends in a word other than a state, even when its envelope shows provisional or final. funding. shows final and ends in raised. trading- shows provisional and ends in triggered. No default pattern matches either name.
An explicit empty list, [], selects no new events. It does not request the defaults. Repeated or overlapping patterns select an endpoint once, rather than creating a copy for each matching pattern. Automatic chain reorganisation corrections for provisional events delivered earlier can still arrive.
An existing endpoint keeps its stored list. The defaults apply only at creation. An update that supplies subscriptions replaces the stored list, so adding one pattern means sending the full list. An update that omits subscriptions leaves the list unchanged.
Events the default subscriptions do not deliver
A new endpoint does not receive these events, because the last part of each name matches no default pattern. The name prefix in the second column delivers the event, and it also delivers the other live events that start with it. The exact event name works as well.
Choose patterns for your integration
Each row maps a need to a list that the platform accepts.
The Console create and edit forms offer *.pending, *.provisional, *.final, *.retracted, and transaction.request.* as checkboxes. The transaction-request option starts unchecked. Their “Event names” field takes any other name prefix or exact name. It lists the published names grouped by their first segment, such as token, and offers a prefix such as token.transfer.* for each family of more than one event. The form refuses a name that matches no published event before it saves.
Related
- Event catalogue: the events of every domain except token sales, trading venues and XvP settlements, when the platform sends each one and what to do with it.
- Market and settlement events: the events of token sales, trading venues and XvP settlements, when the platform sends each one and what to do with it.
- Lifecycle states: what each state means and which sequences an endpoint sees.
- Consuming webhooks: identifiers, deduplication, retries, and retractions on the receiving side.
- Receive DALP webhooks: register an endpoint, verify the signature, and rotate the secret.
- Webhook endpoints in the Console: create an endpoint and choose its subscriptions.