Skip to content

Use the Ripple Custody (Wallet) API to create, list, inspect, and delete webhooks and their subscriptions. A webhook defines the HTTPS endpoint that receives event data. Each subscription attaches a domain — TRANSACTION, WALLET, or APPROVAL — to that webhook. For signature verification, retry behavior, and endpoint requirements, see Receive webhook deliveries. For payload formats, see Webhook event reference.

Webhook actions

ActionConsole roleConsole procedureAPI procedure
Create a webhookOwner, AdministratorCreate a webhookCreate a webhook
Add subscriptions to a webhook--Add subscriptions
List webhooksOwner, Administrator, AuditorView webhooksList webhooks
View a webhookOwner, Administrator, AuditorView webhooksGet a webhook
List subscriptionsOwner, Administrator, AuditorView webhooksList subscriptions
Delete a subscription--Delete a subscription
Delete a webhookOwner, AdministratorDelete a webhookDelete a webhook

Permissions: In the console, owners and administrators can create, update, and delete webhooks, and owners, administrators, and auditors can view them. See User roles and permissions. The API procedures need an API credential of type MONITORING. See Prerequisites.

Prerequisites

  • An API credential of type MONITORING. It grants access to webhooks and webhook subscriptions. API responses return this type's category as AUDIT. Grant the webhook permission with the actions you need — create, read, or delete — at org scope. Create credentials in the console — see Manage API credentials and Credential types.
  • An access token. Exchange your credential's clientId and clientSecret for an access token — see Authenticate.
  • An HTTPS endpoint on your server that returns a 2xx response, such as 200 OK, for each delivery. Ripple Custody (Wallet) rejects webhook endpoints that don't use HTTPS. See Endpoint requirements.

For the base URLs, token lifetime, pagination, filtering, and error format that every endpoint shares, see API conventions.

Create a webhook via the API

API reference: Create webhooks

Call POST /v2/webhooks. name and endpoint are required; description is optional. The name must be unique in your organization: a second webhook with the same name returns 409 with reason PAL015.001. Several webhooks can share an endpoint. An endpoint that doesn't use HTTPS returns 400 with reason PAL000.020.

curl -X POST "https://api.sandbox.palisade.co/v2/webhooks" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Transaction monitor",
    "description": "Notifies the ledger service of transaction status changes",
    "endpoint": "https://hooks.example.com/wallet-events"
  }'

The response is the new webhook. Store its id, and store publicKey to verify the signature on each delivery (see Verify the signature):

{
  "id": "ce4918bf-a199-4ce2-85a3-d0d296855384",
  "organizationId": "21c81319-5b83-45f9-b648-42055084af15",
  "createdBy": "a55df9e0-e14a-4410-a983-12afae46662f",
  "createdAt": "2026-07-23T10:22:22.420Z",
  "updatedBy": "a55df9e0-e14a-4410-a983-12afae46662f",
  "updatedAt": "2026-07-23T10:22:22.420Z",
  "name": "Transaction monitor",
  "description": "Notifies the ledger service of transaction status changes",
  "endpoint": "https://hooks.example.com/wallet-events",
  "subscriptionCount": 0,
  "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEpHiEkdd/ba5dU4sNCgsWrMOE6fLakHywl0OgF5aVfxkiqNh22oybRAREev7jvnwH4jqitHx79KGi6CMwiJjmaw==",
  "lastSuccess": null,
  "lastFailure": null,
  "successCount": 0,
  "failureCount": 0
}

A new webhook has no subscriptions, so it receives no events until you add one.

Add subscriptions via the API

API reference: Create webhook subscriptions

Call POST /v2/webhooks/{webhookId}/subscriptions with a JSON array of subscription configurations, even if you add only one. Each entry needs a domain (TRANSACTION, WALLET, or APPROVAL) and a scope (ORG, the only supported scope). A webhook can have one subscription for each domain: adding a domain it already has returns 409 with reason PAL015.010.

curl -X POST "https://api.sandbox.palisade.co/v2/webhooks/ce4918bf-a199-4ce2-85a3-d0d296855384/subscriptions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "domain": "TRANSACTION", "scope": "ORG" },
    { "domain": "WALLET", "scope": "ORG" }
  ]'

The response is an array of all the webhook's subscriptions, including any it had before the request:

[
  {
    "id": "7b2f4c1e-9a3d-4e8b-b6c5-1d2e3f4a5b6c",
    "webhookId": "ce4918bf-a199-4ce2-85a3-d0d296855384",
    "organizationId": "21c81319-5b83-45f9-b648-42055084af15",
    "createdBy": "a55df9e0-e14a-4410-a983-12afae46662f",
    "createdAt": "2026-07-23T10:23:05.110Z",
    "updatedBy": "a55df9e0-e14a-4410-a983-12afae46662f",
    "updatedAt": "2026-07-23T10:23:05.110Z",
    "config": { "domain": "TRANSACTION", "scope": "ORG" }
  },
  {
    "id": "8c3a5d2f-0b4e-4f9c-a7d6-2e3f4a5b6c7d",
    "webhookId": "ce4918bf-a199-4ce2-85a3-d0d296855384",
    "organizationId": "21c81319-5b83-45f9-b648-42055084af15",
    "createdBy": "a55df9e0-e14a-4410-a983-12afae46662f",
    "createdAt": "2026-07-23T10:23:05.110Z",
    "updatedBy": "a55df9e0-e14a-4410-a983-12afae46662f",
    "updatedAt": "2026-07-23T10:23:05.110Z",
    "config": { "domain": "WALLET", "scope": "ORG" }
  }
]

List webhooks via the API

API reference: List webhooks, List webhooks with a request body

Call GET /v2/webhooks to retrieve your organization's webhooks. You can:

  • Search — search runs a case-insensitive search over webhook ID, name, description, and endpoint.
  • Filter — use filter.<field>.<operator> on id, name, description, endpoint, createdAt, updatedAt, lastSuccess, and lastFailure. For example, filter.lastFailure.relativeDays=-1 finds webhooks with a failed delivery in the last day.
  • Sort — set pagination.orderBy to name, endpoint, created_at, updated_at, last_success, or last_failure, and pagination.order to SORT_ORDER_ASC or SORT_ORDER_DESC.
  • Page — pagination.pageSize sets the page size. To get the next page, pass the previous response's filter.nextPageToken as pagination.pageToken.

For complex filters, send filter, pagination, and search as a JSON body to POST /v2/webhooks:list instead.

curl -X GET "https://api.sandbox.palisade.co/v2/webhooks?search=transaction&pagination.pageSize=10" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The response contains a webhooks array and a filter object with pagination metadata:

{
  "filter": { "total": 1 },
  "webhooks": [
    {
      "id": "ce4918bf-a199-4ce2-85a3-d0d296855384",
      "organizationId": "21c81319-5b83-45f9-b648-42055084af15",
      "createdBy": "a55df9e0-e14a-4410-a983-12afae46662f",
      "createdAt": "2026-07-23T10:22:22.420Z",
      "updatedBy": "a55df9e0-e14a-4410-a983-12afae46662f",
      "updatedAt": "2026-07-23T10:22:22.420Z",
      "name": "Transaction monitor",
      "description": "Notifies the ledger service of transaction status changes",
      "endpoint": "https://hooks.example.com/wallet-events",
      "subscriptionCount": 2,
      "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEpHiEkdd/ba5dU4sNCgsWrMOE6fLakHywl0OgF5aVfxkiqNh22oybRAREev7jvnwH4jqitHx79KGi6CMwiJjmaw==",
      "lastSuccess": "2026-07-24T08:15:02.391Z",
      "lastFailure": null,
      "successCount": 42,
      "failureCount": 0
    }
  ]
}

Get a webhook via the API

API reference: Get webhooks

Call GET /v2/webhooks/{id} to inspect a single webhook, including its delivery health:

  • successCount and failureCount — the number of successful and failed deliveries in the last hour.
  • lastSuccess and lastFailure — the times of the most recent successful and failed deliveries. Each is null until a delivery of that kind occurs.
  • publicKey — the public key that verifies the signature on each delivery.
curl -X GET "https://api.sandbox.palisade.co/v2/webhooks/ce4918bf-a199-4ce2-85a3-d0d296855384" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The response is a single webhook object with the same fields as an entry in the list response.

List subscriptions via the API

API reference: List subscriptions, List subscriptions with a request body

Call GET /v2/webhooks/{webhookId}/subscriptions to see what a webhook is subscribed to. Filter by domain with filter.domain (for example, filter.domain=TRANSACTION) or by scope with filter.scope. You can also filter on id, webhookId, createdAt, and updatedAt, sort by domain, scope, created_at, or updated_at, and page with pagination.pageSize and pagination.pageToken. For complex filters, use POST /v2/webhooks/{webhookId}/subscriptions:list with a JSON body.

curl -X GET "https://api.sandbox.palisade.co/v2/webhooks/ce4918bf-a199-4ce2-85a3-d0d296855384/subscriptions?filter.domain=TRANSACTION" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
{
  "filter": { "total": 1 },
  "subscriptions": [
    {
      "id": "7b2f4c1e-9a3d-4e8b-b6c5-1d2e3f4a5b6c",
      "webhookId": "ce4918bf-a199-4ce2-85a3-d0d296855384",
      "organizationId": "21c81319-5b83-45f9-b648-42055084af15",
      "createdBy": "a55df9e0-e14a-4410-a983-12afae46662f",
      "createdAt": "2026-07-23T10:23:05.110Z",
      "updatedBy": "a55df9e0-e14a-4410-a983-12afae46662f",
      "updatedAt": "2026-07-23T10:23:05.110Z",
      "config": { "domain": "TRANSACTION", "scope": "ORG" }
    }
  ]
}

Get a subscription via the API

API reference: Get subscriptions

Call GET /v2/webhooks/{webhookId}/subscriptions/{subscriptionId} to inspect a single subscription. The response is a single subscription object with the same fields as an entry in the list response.

curl -X GET "https://api.sandbox.palisade.co/v2/webhooks/ce4918bf-a199-4ce2-85a3-d0d296855384/subscriptions/7b2f4c1e-9a3d-4e8b-b6c5-1d2e3f4a5b6c" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Delete a subscription via the API

API reference: Delete subscriptions

Call DELETE /v2/webhooks/{webhookId}/subscriptions/{subscriptionId} to stop the webhook from receiving events for that subscription's domain. A successful response returns an empty JSON object.

curl -X DELETE "https://api.sandbox.palisade.co/v2/webhooks/ce4918bf-a199-4ce2-85a3-d0d296855384/subscriptions/7b2f4c1e-9a3d-4e8b-b6c5-1d2e3f4a5b6c" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
{}

Delete a webhook via the API

API reference: Delete webhooks

Call DELETE /v2/webhooks/{id} to remove a webhook. A successful response returns an empty JSON object.

Deletion is permanent

Deleting a webhook stops all deliveries to its endpoint. To resume deliveries, create a new webhook and add its subscriptions again. The new webhook has a new publicKey, so update your signature verification.

curl -X DELETE "https://api.sandbox.palisade.co/v2/webhooks/ce4918bf-a199-4ce2-85a3-d0d296855384" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
{}
Updating a webhook

Neither the API nor the console can update a webhook's name, description, or endpoint. The API has no update operation: PUT or PATCH on /v2/webhooks/{id} returns 501 with the message Method Not Allowed. To change them, delete the webhook and create a new one. See Update a webhook. To change which events a webhook receives, add or delete subscriptions.

Manage webhooks via the console

Receive webhook deliveries