Skip to navigation
Yoco APIWebhooks

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 or out of order. For time-critical decisions, confirm the current status through the API instead of relying only on webhooks.

Create webhook subscription Returns subscription (with secret) POST event to notification URL 2xx response A payment occurs Your application Yoco API

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.

Event types

For the full list of available event types and example payloads, see the webhook events reference.