> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.yoco.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.yoco.com/_mcp/server.

# Webhooks

Webhooks let your app receive notifications shortly after events occur in a Yoco account.
Instead of polling the API for updates, Yoco pushes event data to an HTTPS endpoint you specify.

Common use cases include:

* **Updating order status**: mark an order as paid in your system when a `payment.created` event
  arrives.
* **Sending receipts**: trigger a confirmation email to the customer after a successful payment.
* **Processing refunds**: update your accounting records or notify support when a `payment.refunded`
  event is received.

## How it works

Yoco uses a subscription-based webhook model. You create a **webhook subscription** that specifies
which event types you want to receive and the URL to notify. When a matching event occurs, Yoco
sends an HTTPS `POST` request to your endpoint with the event payload in JSON format. Delivery is
asynchronous, so exact delivery times aren't guaranteed. Retries and service disruptions can delay
events, and events can arrive
[more than once](/docs/api/webhooks/best-practices#handle-duplicate-deliveries) or
[out of order](/docs/api/webhooks/best-practices#handle-events-out-of-order). For time-critical
decisions, confirm the current status through the API instead of relying only on webhooks.

```mermaid
sequenceDiagram
    participant App as Your application
    participant Yoco as Yoco API
    App->>Yoco: Create webhook subscription
    Yoco-->>App: Returns subscription (with secret)
    Note over App: A payment occurs
    Yoco->>App: POST event to notification URL
    App-->>Yoco: 2xx response
```

Your endpoint must respond with a `2xx` HTTP status code within 15 seconds to acknowledge receipt.
If it doesn't, Yoco retries delivery according to a
[retry schedule](/docs/api/webhooks/handling-events#retry-behaviour).

## Event types

For the full list of available event types and example payloads, see the
[webhook events reference](/api-reference/yoco-api/webhook-events).