Skip to main content
Webhooks let you react to changes in your users’ financial data as they happen. Instead of polling the API, Yoshi sends an HTTP POST request to your server whenever an event occurs — a new transaction is synced, a balance updates, an account is connected, and more.

​
How it works

1

Register an endpoint

Tell Yoshi where to send events by creating a webhook endpoint via the API or the self-service portal. You provide an HTTPS URL and optionally choose which event types to receive.
2

Yoshi detects a change

When a user’s financial data changes — new transactions arrive from their bank, a balance refreshes, or an account is linked — Yoshi generates a webhook event.
3

Your server receives the event

Yoshi sends an HTTP POST to your endpoint with the event payload. Each request is signed so you can verify it came from Yoshi.
4

You respond with 200

Return a 2xx status code within 15 seconds to acknowledge receipt. Process the event asynchronously — don’t do heavy work in the handler.

​
Event envelope

Every webhook event follows the same structure: 
{
  "id": "evt_2KWPBQMnRE2EqH9WlXbQTzSGeAT",
  "type": "transaction.created",
  "created_at": "2026-04-10T14:30:00.000Z",
  "api_version": "2026-04-10",
  "data": {
    "account_id": "acc_xyz789",
    "transaction_ids": ["txn_abc123", "txn_def456"],
    "count": 2
  }
}
FieldDescription
idUnique event identifier. Stable across retries — use it for idempotency.
typeDot-notation event type, e.g. transaction.created. See the full event catalog.
created_atISO 8601 timestamp of when the event occurred.
api_versionThe API version that generated this event. Currently 2026-04-10.
dataEvent-specific payload. Contains resource IDs and non-sensitive metadata.
Webhook payloads contain resource IDs and metadata, not full resource objects. To fetch complete details, call the corresponding API endpoint with the ID from the event. This keeps payloads small and minimizes sensitive data in transit.

​
Security

Every webhook request includes three headers for signature verification:
HeaderDescription
webhook-idUnique message identifier
webhook-timestampUnix timestamp (seconds) when the webhook was sent
webhook-signatureHMAC-SHA256 signature for verifying authenticity
Always verify signatures before processing events. The SDKs include a built-in helper that handles verification and replay protection automatically.

​
Consumer portal

Every API key holder has access to a self-service webhook portal for managing endpoints, viewing delivery logs, and replaying failed events. Generate a portal link via the API: 
curl https://api.yoshi.ai/v1/webhooks/portal \
  -H "Authorization: Bearer yoshi_3xK9mP..."
The response contains a one-time URL that opens the portal: 
{
  "data": {
    "url": "https://app.svix.com/login#key=..."
  },
  "meta": {
    "request_id": "req_a1b2c3d4",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}
The portal lets you:
  • Create, edit, and delete webhook endpoints
  • View delivery attempts with response codes
  • Replay failed events with one click
  • Browse the event log with full payloads

​
What’s next

Event catalog

Browse all available event types and their payloads.

Verify signatures

Ensure webhook requests are authentic.

Delivery and retries

Understand retry behavior and idempotency.

Manage endpoints

Register and configure webhook endpoints via the API.
Last modified on April 17, 2026