Effect
An effect declares a subscription to ledger changes. When a matching change occurs, the ledger delivers a notification to the configured endpoint. Each effect specifies a signal to watch and optional filters to narrow which changes trigger a notification.
For example, an effect can subscribe to payment completions on a specific wallet, and the ledger will deliver a webhook to your service each time it happens.
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /effects | Register an event subscription that delivers notifications to an external endpoint. |
| GET | /effects | Query effects with filtering, sorting, and pagination. |
| GET | /effects/{id} | Retrieve an effect by its handle or LUID. |
| PUT | /effects/{id} | Submit a new version of an effect. |
| DELETE | /effects/{id} | Permanently remove an effect from the ledger. |
| POST | /effects/{id}/proofs | Submit a signed proof to an effect record. |
Actions
| Method | Path | Description |
|---|---|---|
| POST | /effects/{id}/activate | Retry failed or pending event deliveries for an effect. |
| POST | /effects/{id}/events/retry | Retry failed or pending event deliveries for an effect. |
Access & History
| Method | Path | Description |
|---|---|---|
| POST | /effects/{id}/access/!check | Evaluate what actions a signer can perform on this effect. |
| GET | /effects/{id}/changes | Retrieve the change history of an effect by its handle or LUID. |
| GET | /effects/{id}/changes/{change} | Retrieve a change record for an effect by handle or LUID and change number. |
Related
- Extending Ledger — the integration model for effects and bridges
- Register an Effect — how to register and configure an effect
Get bridge change GET
Returns a single change by its sequence number. The change includes a full record snapshot as it existed at that point.
Create effect POST
The effect begins delivering events immediately after creation. Each event matching the declared signal and optional filter is delivered asynchronously to the configured endpoint. Delivery actions include `webhook` for direct HTTP delivery and `bridge` to route events through a bridge's security and retry mechanisms. Failed deliveries are retried automatically with exponential backoff. Filters use a MongoDB-style query syntax on the event data, allowing granular control over which events trigger delivery. Broadcasts the `effect-created` signal.