Manage webhook endpoints

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.

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

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"
  }
}

For full payload examples, see the event catalog.

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

Getting Started

Reference

SDKs

Concepts

Webhooks

Use Cases

Tools

Resources

Manage webhook endpoints

Create an endpoint

List endpoints

Get an endpoint

Update an endpoint

Delete an endpoint

Rotate signing secret

List event types

API reference

​Create an endpoint

​List endpoints

​Get an endpoint

​Update an endpoint

​Delete an endpoint

​Rotate signing secret

​List event types

​API reference

Create an endpoint

List endpoints

Get an endpoint

Update an endpoint

Delete an endpoint

Rotate signing secret

List event types

API reference