> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yoshi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage webhook endpoints

> Create, update, list, and delete webhook endpoints via the API. Configure event filters, rotate signing secrets, and manage endpoint lifecycle.

Manage your webhook endpoints programmatically through the `/v1/webhooks` API. All endpoints require authentication with your API key.

## Create an endpoint

Register a new webhook endpoint. You'll receive a signing secret in the response — **store it securely**, as it's only shown once.

```bash theme={null}
curl -X POST https://api.yoshi.ai/v1/webhooks/endpoints \
  -H "Authorization: Bearer yoshi_3xK9mP..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/yoshi",
    "description": "Production webhook handler",
    "filter_types": ["transaction.created", "account.connected"]
  }'
```

```json theme={null}
{
  "data": {
    "id": "ep_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "url": "https://example.com/webhooks/yoshi",
    "description": "Production webhook handler",
    "filter_types": ["transaction.created", "account.connected"],
    "status": "active",
    "secret": "whsec_REPLACE_WITH_YOUR_SIGNING_SECRET",
    "created_at": "2026-04-10T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_a1b2c3d4",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}
```

| Parameter      | Type       | Required | Description                                                                                                      |
| -------------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `url`          | `string`   | Yes      | HTTPS URL where events will be delivered.                                                                        |
| `description`  | `string`   | No       | Human-readable label for the endpoint. Max 256 characters.                                                       |
| `filter_types` | `string[]` | No       | Event types to subscribe to. Empty array or omitted means all events. See the [event catalog](/webhooks/events). |

<Warning>
  The `secret` field is only included in the create response. Store it immediately in a secure location like an environment variable or secrets manager. If you lose it, you can [rotate](#rotate-signing-secret) to get a new one.
</Warning>

**Limits:** You can register up to **5 active endpoints** per API key. URLs must use HTTPS.

## List endpoints

```bash theme={null}
curl https://api.yoshi.ai/v1/webhooks/endpoints \
  -H "Authorization: Bearer yoshi_3xK9mP..."
```

```json theme={null}
{
  "data": {
    "endpoints": [
      {
        "id": "ep_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "url": "https://example.com/webhooks/yoshi",
        "description": "Production webhook handler",
        "filter_types": ["transaction.created", "account.connected"],
        "status": "active",
        "created_at": "2026-04-10T12:00:00.000Z",
        "updated_at": "2026-04-10T12:00:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_a1b2c3d4",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}
```

## Get an endpoint

```bash theme={null}
curl https://api.yoshi.ai/v1/webhooks/endpoints/{endpoint_id} \
  -H "Authorization: Bearer yoshi_3xK9mP..."
```

## Update an endpoint

Update the URL, description, event filters, or status of an existing endpoint. Only include the fields you want to change.

```bash theme={null}
curl -X PUT https://api.yoshi.ai/v1/webhooks/endpoints/{endpoint_id} \
  -H "Authorization: Bearer yoshi_3xK9mP..." \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated production handler",
    "filter_types": ["transaction.created", "balance.updated"],
    "status": "active"
  }'
```

| Parameter      | Type             | Description                                              |
| -------------- | ---------------- | -------------------------------------------------------- |
| `url`          | `string`         | New HTTPS URL.                                           |
| `description`  | `string \| null` | Updated description, or `null` to clear.                 |
| `filter_types` | `string[]`       | Updated event type filter. Empty array means all events. |
| `status`       | `string`         | `"active"` or `"disabled"`.                              |

## Delete an endpoint

Permanently remove a webhook endpoint. This immediately stops all future deliveries to this URL.

```bash theme={null}
curl -X DELETE https://api.yoshi.ai/v1/webhooks/endpoints/{endpoint_id} \
  -H "Authorization: Bearer yoshi_3xK9mP..."
```

```json theme={null}
{
  "data": {
    "deleted": true
  },
  "meta": {
    "request_id": "req_a1b2c3d4",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}
```

## Rotate signing secret

Generate a new signing secret for an endpoint. During the rotation window, both the old and new secrets are valid — see the [verification guide](/webhooks/verification#secret-rotation) for handling this.

```bash theme={null}
curl -X POST https://api.yoshi.ai/v1/webhooks/endpoints/{endpoint_id}/rotate \
  -H "Authorization: Bearer yoshi_3xK9mP..."
```

```json theme={null}
{
  "data": {
    "secret": "whsec_REPLACE_WITH_YOUR_ROTATED_SECRET"
  },
  "meta": {
    "request_id": "req_a1b2c3d4",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}
```

<Warning>
  Store the new secret immediately. Like the initial secret, it is only returned once.
</Warning>

## List event types

Get all available event types that you can subscribe to:

```bash theme={null}
curl https://api.yoshi.ai/v1/webhooks/events \
  -H "Authorization: Bearer yoshi_3xK9mP..."
```

```json theme={null}
{
  "data": {
    "event_types": [
      { "type": "account.connected", "description": "A new financial account was linked." },
      { "type": "account.disconnected", "description": "Account access was revoked." },
      { "type": "transaction.created", "description": "New transaction(s) synced from institution." },
      { "type": "balance.updated", "description": "Account balance refreshed." },
      { "type": "score.updated", "description": "Financial health scores recalculated." }
    ]
  },
  "meta": {
    "request_id": "req_a1b2c3d4",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}
```

For full payload examples, see the [event catalog](/webhooks/events).

## API reference

| Method   | Endpoint                             | Description                 |
| -------- | ------------------------------------ | --------------------------- |
| `POST`   | `/v1/webhooks/endpoints`             | Create a webhook endpoint   |
| `GET`    | `/v1/webhooks/endpoints`             | List all endpoints          |
| `GET`    | `/v1/webhooks/endpoints/{id}`        | Get endpoint details        |
| `PUT`    | `/v1/webhooks/endpoints/{id}`        | Update an endpoint          |
| `DELETE` | `/v1/webhooks/endpoints/{id}`        | Delete an endpoint          |
| `POST`   | `/v1/webhooks/endpoints/{id}/test`   | Send a test event           |
| `POST`   | `/v1/webhooks/endpoints/{id}/rotate` | Rotate signing secret       |
| `GET`    | `/v1/webhooks/events`                | List available event types  |
| `GET`    | `/v1/webhooks/deliveries`            | List delivery attempts      |
| `GET`    | `/v1/webhooks/portal`                | Get self-service portal URL |