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.
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"]
}'
{
"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. |
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 to get a new one. List endpoints
curl https://api.yoshi.ai/v1/webhooks/endpoints \
-H "Authorization: Bearer yoshi_3xK9mP..."
{
"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
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.
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.
curl -X DELETE https://api.yoshi.ai/v1/webhooks/endpoints/{endpoint_id} \
-H "Authorization: Bearer yoshi_3xK9mP..."
{
"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 for handling this.
curl -X POST https://api.yoshi.ai/v1/webhooks/endpoints/{endpoint_id}/rotate \
-H "Authorization: Bearer yoshi_3xK9mP..."
{
"data": {
"secret": "whsec_REPLACE_WITH_YOUR_ROTATED_SECRET"
},
"meta": {
"request_id": "req_a1b2c3d4",
"timestamp": "2026-04-10T12:00:00.000Z"
}
}
Store the new secret immediately. Like the initial secret, it is only returned once.
List event types
Get all available event types that you can subscribe to:
curl https://api.yoshi.ai/v1/webhooks/events \
-H "Authorization: Bearer yoshi_3xK9mP..."
{
"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"
}
}
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 |
