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

# Webhooks for real-time financial data updates

> Receive real-time HTTP callbacks from Yoshi when financial data changes. Covers event structure, security headers, and the self-service portal.

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

<Steps>
  <Step title="Register an endpoint">
    Tell Yoshi where to send events by creating a webhook endpoint via the API or the [self-service portal](#consumer-portal). You provide an HTTPS URL and optionally choose which event types to receive.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](/webhooks/verification) it came from Yoshi.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Event envelope

Every webhook event follows the same structure:

```json theme={null}
{
  "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
  }
}
```

| Field         | Description                                                                                                |
| ------------- | ---------------------------------------------------------------------------------------------------------- |
| `id`          | Unique event identifier. Stable across retries — use it for [idempotency](/webhooks/delivery#idempotency). |
| `type`        | Dot-notation event type, e.g. `transaction.created`. See the full [event catalog](/webhooks/events).       |
| `created_at`  | ISO 8601 timestamp of when the event occurred.                                                             |
| `api_version` | The API version that generated this event. Currently `2026-04-10`.                                         |
| `data`        | Event-specific payload. Contains resource IDs and non-sensitive metadata.                                  |

<Info>
  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.
</Info>

## Security

Every webhook request includes three headers for [signature verification](/webhooks/verification):

| Header              | Description                                        |
| ------------------- | -------------------------------------------------- |
| `webhook-id`        | Unique message identifier                          |
| `webhook-timestamp` | Unix timestamp (seconds) when the webhook was sent |
| `webhook-signature` | HMAC-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:

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

The response contains a one-time URL that opens the portal:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Event catalog" icon="list" href="/webhooks/events">
    Browse all available event types and their payloads.
  </Card>

  <Card title="Verify signatures" icon="shield-check" href="/webhooks/verification">
    Ensure webhook requests are authentic.
  </Card>

  <Card title="Delivery and retries" icon="rotate" href="/webhooks/delivery">
    Understand retry behavior and idempotency.
  </Card>

  <Card title="Manage endpoints" icon="gear" href="/webhooks/management">
    Register and configure webhook endpoints via the API.
  </Card>
</CardGroup>