# Manage webhooks via the API

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](/pt-br/products/wallet/integrations-and-monitoring/webhooks/receive-webhook-deliveries). For payload formats, see [Webhook event reference](/pt-br/products/wallet/integrations-and-monitoring/webhooks/webhook-event-reference).

## Webhook actions

| Action | Console role | Console procedure | API procedure |
|  --- | --- | --- | --- |
| Create a webhook | Owner, Administrator | [Create a webhook](/pt-br/products/wallet/integrations-and-monitoring/webhooks/manage-webhooks#create-a-webhook-via-the-console) | [Create a webhook](#create-a-webhook-via-the-api) |
| Add subscriptions to a webhook | - | - | [Add subscriptions](#add-subscriptions-via-the-api) |
| List webhooks | Owner, Administrator, Auditor | [View webhooks](/pt-br/products/wallet/integrations-and-monitoring/webhooks/manage-webhooks#view-webhooks-via-the-console) | [List webhooks](#list-webhooks-via-the-api) |
| View a webhook | Owner, Administrator, Auditor | [View webhooks](/pt-br/products/wallet/integrations-and-monitoring/webhooks/manage-webhooks#view-webhooks-via-the-console) | [Get a webhook](#get-a-webhook-via-the-api) |
| List subscriptions | Owner, Administrator, Auditor | [View webhooks](/pt-br/products/wallet/integrations-and-monitoring/webhooks/manage-webhooks#view-webhooks-via-the-console) | [List subscriptions](#list-subscriptions-via-the-api) |
| Delete a subscription | - | - | [Delete a subscription](#delete-a-subscription-via-the-api) |
| Delete a webhook | Owner, Administrator | [Delete a webhook](/pt-br/products/wallet/integrations-and-monitoring/webhooks/manage-webhooks#delete-a-webhook-via-the-console) | [Delete a webhook](#delete-a-webhook-via-the-api) |


**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](/pt-br/products/wallet/organization-and-access/users-and-roles#webhooks). The API procedures need an API credential of type `MONITORING`. See [Prerequisites](#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](/pt-br/products/wallet/organization-and-access/api-credentials/manage-api-credentials) and [Credential types](/pt-br/products/wallet/organization-and-access/api-credentials#credential-types).
- **An access token.** Exchange your credential's `clientId` and `clientSecret` for an access token — see [Authenticate](/pt-br/products/wallet/get-started/use-the-api#step-2-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](/pt-br/products/wallet/integrations-and-monitoring/webhooks/receive-webhook-deliveries#endpoint-requirements).


For the base URLs, token lifetime, pagination, filtering, and error format that every endpoint shares, see [API conventions](/pt-br/products/wallet/api-and-developer-experience/api-conventions).

## Create a webhook via the API

**API reference:** [Create webhooks](/pt-br/products/wallet/api-docs/palisade-api/palisade-api/webhooks/webhookservice_createwebhook)

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`.

```bash
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](/pt-br/products/wallet/integrations-and-monitoring/webhooks/receive-webhook-deliveries#verify-the-signature)):

```json
{
  "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](/pt-br/products/wallet/api-docs/palisade-api/palisade-api/webhooks/webhookservice_createsubscriptions)

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`.

```bash
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:

```json
[
  {
    "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](/pt-br/products/wallet/api-docs/palisade-api/palisade-api/webhooks/webhookservice_listwebhooks), [List webhooks with a request body](/pt-br/products/wallet/api-docs/palisade-api/palisade-api/webhooks/webhookservice_listwebhooks2)

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.

```bash
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:

```json
{
  "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](/pt-br/products/wallet/api-docs/palisade-api/palisade-api/webhooks/webhookservice_getwebhook)

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.


```bash
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](/pt-br/products/wallet/api-docs/palisade-api/palisade-api/webhooks/webhookservice_listsubscriptions), [List subscriptions with a request body](/pt-br/products/wallet/api-docs/palisade-api/palisade-api/webhooks/webhookservice_listsubscriptions2)

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.

```bash
curl -X GET "https://api.sandbox.palisade.co/v2/webhooks/ce4918bf-a199-4ce2-85a3-d0d296855384/subscriptions?filter.domain=TRANSACTION" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json
{
  "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](/pt-br/products/wallet/api-docs/palisade-api/palisade-api/webhooks/webhookservice_getsubscription)

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.

```bash
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](/pt-br/products/wallet/api-docs/palisade-api/palisade-api/webhooks/webhookservice_deletesubscription)

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.

```bash
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"
```

```json
{}
```

## Delete a webhook via the API

**API reference:** [Delete webhooks](/pt-br/products/wallet/api-docs/palisade-api/palisade-api/webhooks/webhookservice_deletewebhook)

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.

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

```json
{}
```

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](/pt-br/products/wallet/integrations-and-monitoring/webhooks/manage-webhooks#update-a-webhook). To change which events a webhook receives, add or delete subscriptions.

## Related topics

- [Manage webhooks via the console](/pt-br/products/wallet/integrations-and-monitoring/webhooks/manage-webhooks) — Create, view, and delete webhooks in the console
- [Receive webhook deliveries](/pt-br/products/wallet/integrations-and-monitoring/webhooks/receive-webhook-deliveries) — Verify signatures, handle retries, and process events safely
- [Webhook event reference](/pt-br/products/wallet/integrations-and-monitoring/webhooks/webhook-event-reference) — The envelope and the payload for each domain
- [Webhooks](/pt-br/products/wallet/integrations-and-monitoring/webhooks) — What webhooks are, how delivery works, and subscription domains
- [Ripple Custody (Wallet) API reference](/pt-br/products/wallet/api-docs/palisade-api/palisade-api) — Full request and response schemas