> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waycore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive real-time event notifications

Webhooks let you subscribe to events instead of polling the API. When a subscribed event occurs, Waycore sends an HTTP `POST` to your registered URL with a signed JSON payload.

Today, webhooks are an operational signal layer, not a complete replay feed. In particular, `transactions.sync_available` tells you to call `GET /v1/transactions/sync`; it is not itself a transaction reconciliation stream.

## Registering an endpoint

Create a webhook registration with `POST /v1/webhooks`, specifying the delivery URL and the event types you want to receive. The response includes a signing `secret` — store it securely, as it is only shown in full once.

Alternatively, you can register a webhook manually using the [Waycore Console](https://console.waycore.com).

## Verifying deliveries

Every delivery includes a `Waycore-Signature` header in the format:

```text theme={null}
t=<unix>,v1=<hex>
```

`v1` is the HMAC-SHA256 of:

```text theme={null}
<timestamp>.<raw_body>
```

Always verify the signature against the raw request body before processing the event.

## Event types

| Event                         | Status today           | Notes                                                                                                                                                        |
| ----------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `connection.status_changed`   | Emitted                | Fired when a connection changes status.                                                                                                                      |
| `account.created`             | Reserved               | Not currently emitted by production-facing flows.                                                                                                            |
| `account.updated`             | Reserved               | Not currently emitted by production-facing flows.                                                                                                            |
| `transactions.sync_available` | Emitted                | Indicates fresh transaction data is ready. Call `GET /v1/transactions/sync`. Deliveries are currently connection-scoped, so `accountId` is currently `null`. |
| `transfer.status_changed`     | Reserved               | Reserved for future transfer status notifications.                                                                                                           |
| `test`                        | Explicitly triggerable | Can be queued through the API when the webhook is active and subscribed to `test`.                                                                           |

## Event envelope

Every delivery shares the same outer structure:

```json theme={null}
{
  "id": "evt_abc123",
  "type": "transactions.sync_available",
  "createdAt": "2026-03-04T12:00:00Z",
  "data": { ... }
}
```

Use `id` as an idempotency key. Your endpoint may receive the same event more than once.

## Retry behavior

Waycore retries unacknowledged deliveries with exponential backoff when the endpoint returns a non-2xx response or times out. Return a `2xx` response as quickly as possible and process the event asynchronously.

## Testing a webhook

Use `POST /v1/webhooks/{webhookId}/test` to queue a synthetic `test` event for a single registration. The webhook must be active and already subscribed to the `test` event type.

## Managing registrations

<CardGroup cols={3}>
  <Card title="Create webhook" icon="plus" href="/api-reference/webhooks/create-webhook" />

  <Card title="List webhooks" icon="list" href="/api-reference/webhooks/list-webhooks" />

  <Card title="Get webhook" icon="search" href="/api-reference/webhooks/get-webhook" />

  <Card title="Update webhook" icon="pen" href="/api-reference/webhooks/update-webhook" />

  <Card title="Delete webhook" icon="trash" href="/api-reference/webhooks/delete-webhook" />

  <Card title="Trigger test webhook" icon="flask-conical" href="/api-reference/webhooks/trigger-test-webhook" />
</CardGroup>

## Required scopes

| Scope            | Used by                              |
| ---------------- | ------------------------------------ |
| `webhooks:write` | Create, update, delete, trigger test |
| `webhooks:read`  | List, get                            |