> ## 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.