ReferenceAPI ReferenceEffect

Create effect

POST/effects●Register an event subscription that delivers notifications to an external endpoint.

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.

POST
/effects

Usage Examples

curl -X POST "http://localhost:3000/v2/effects" \  -H "x-ledger: <YOUR LEDGER HANDLE>" \  -H "Content-Type: application/json" \  -d '{    "hash": "92a858f132198ba17f4e9bafbfd2fa55f521236cb4780e2cb335f02c29840d55",    "data": {      "handle": "intent-created",      "signal": "intent-created",      "action": {        "bridge": "tesla-bank-bridge"      }    },    "meta": {      "proofs": [        {          "method": "ed25519-v2",          "digest": "4002631f636059f68e31bc8e517f026daf592ec6f9cf2a311af1b89048b58802",          "public": "dsZvr0rEw9sIffHlv1VP65x1NB8GeXezIv6HONk1SIk=",          "result": "jUI71kR80f3uIRrj2oaot+k7STGxmibE6YTIx42OxaFKgKvaOw7d1JSxIp2Qf488czdt9hurVzgElOpnZb2qBA==",          "custom": {            "moment": "2025-04-05T14:30:00.000Z",            "status": "created"          }        }      ]    }  }'
{
  "luid": "$eff.-01xK5vWxY6hW8AB7",
  "hash": "92a858f132198ba17f4e9bafbfd2fa55f521236cb4780e2cb335f02c29840d55",
  "data": {
    "handle": "intent-created",
    "signal": "intent-created",
    "action": {
      "bridge": "tesla-bank-bridge"
    }
  },
  "meta": {
    "status": "created",
    "moment": "2025-04-05T14:30:00.050Z",
    "owners": [
      "dsZvr0rEw9sIffHlv1VP65x1NB8GeXezIv6HONk1SIk="
    ],
    "proofs": [
      {
        "signer": "tesla-bank-admin",
        "method": "ed25519-v2",
        "digest": "4002631f636059f68e31bc8e517f026daf592ec6f9cf2a311af1b89048b58802",
        "public": "dsZvr0rEw9sIffHlv1VP65x1NB8GeXezIv6HONk1SIk=",
        "result": "jUI71kR80f3uIRrj2oaot+k7STGxmibE6YTIx42OxaFKgKvaOw7d1JSxIp2Qf488czdt9hurVzgElOpnZb2qBA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z",
          "status": "created"
        }
      },
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "b90e717212ccaea9f46c7bae5206905daaa67f3b5f0f9ef058dae036955c0276",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "7WaxRr3Uff7fxLs+I0wlc/htE5OwyMIi4ahIIq7p3ZG2itgBT9O+Gxqk46Zjf6HeKB1GjLjQXWMmndxMSFyvCQ==",
        "custom": {
          "luid": "$eff.-01xK5vWxY6hW8AB7",
          "moment": "2025-04-05T14:30:00.050Z",
          "status": "created"
        }
      }
    ]
  }
}
{
  "hash": "b7eb7ccf5ffc126951e13e29a8dcfdaf95db859715d4edfc2d16f59a79d4cd58",
  "data": {
    "reason": "auth.unauthorized",
    "detail": "Invalid token."
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "3acece870c4118bfe4223118e4d2f3cfd5b8947a7093785b66d49aa57fa2890a",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "gnK63DqqWDY/UXvnZHixDKPKS6tfeGHgdARylnPiJLwQGyYxuD97TYbSg2wrzsf/bDrHwQYZaf8Gu5ryYP0UAA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}
{
  "hash": "9ec02726b50650add8acfd124c6defeb978a9ac252a5de888f9493ddc701e927",
  "data": {
    "reason": "auth.forbidden",
    "detail": "Request is not authorized"
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "4f8cbdc38d73348de0c31805c783c84a0fecc6be736d7e187004ba68cd00e675",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "P3hRnveehtuobb4AIO56XBmiduvmYJbpdmOHltG/IifBEH7QSWdv/0pqled4SO9x1Ne3oXuWxJy40DzMvx1MBA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}
{
  "hash": "dc973d46dd35baa27b0ec5a107e2ee3a8cc57116d086dd868dd0f044a8de7d92",
  "data": {
    "reason": "record.duplicated",
    "detail": "Ledger with handle instant-payments already exists."
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "3e1317cc165d132f95ec2f6374890063c162d905d86b33270f97416f8441a872",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "b+0gSDCUzjEKlZQ/c40yqNpZoyQxCFsbV1Ut5/0zM2wM46xmHMBj3qeo3/GDaFD4NgSNm2G8n1f9c9rfvkl3BA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

{
  "hash": "1c084e8dcfb9bb84bc8ea96e9e137b149a34b2bbd85f8e60b4263f5aba980476",
  "data": {
    "custom": {
      "errors": [
        {
          "instancePath": "/handle",
          "schemaPath": "#/properties/handle/pattern",
          "keyword": "pattern",
          "params": {
            "pattern": "^[a-zA-Z0-9_\\-+.]+$"
          },
          "message": "must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
        }
      ]
    },
    "reason": "record.schema-invalid",
    "detail": "Schema validator error: data.handle must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "7a5febb431719b6f43d7e88e79211308e16ac651b71b339276373fdb4e7c3760",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "2/1zYw4AaIzsIHfOIC6V/CHw6owbjYHt48cwmFOig0ibeT0IbojLmj1RCRi8W00ka0udPa9WsacWDd7ObMY8CA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

{
  "hash": "93a5f4d97a42c2df97f827c58ff7768d02568c15aca931e22b81fa3160ba0df3",
  "data": {
    "reason": "api.unexpected-error",
    "detail": "An unexpected error occurred"
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "efaf5360143b586917d9636779ad6e08571c5b06909a20dd0f5eba4bf3be7eae",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "hERh6Aecj59iR+Fb25OQsHJScOi4t8EiffKSfjlMQdjHMccTnfDlgZFdaJzXzUtpSwy/NHq0l+7ydh3HSWCoAg==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

Header Parameters

x-ledger?|

The unique identifier of ledger in context for multi tenant requests.

Request Body

application/json

Effect body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

Effect

Subscribe to ledger changes and receive notifications when they happen.

List effects GET

Use this endpoint to review configured event subscriptions, identify which effects are listening for a specific signal, or audit event routing configuration across your ledger. Supported filters: - `data.schema` — effect schema - `meta.status` — record status - `meta.labels` — record labels - `meta.domain` — domain scope - `data.custom.<field>` — any custom field (may be slower on large datasets)