Listen for events

Webhooks are used to handle requests that may take longer to process, such as payments or refunds.

Instead of waiting for an immediate response, webhooks provide real-time notifications once these events are completed. This ensures that you remain updated without the need for constant polling or manual checks.

To start receiving webhook events, you need to create an endpoint for handling webhook notifications and then register it.

important

We suggest using a tunneling service such as ngrok to test your webhook implementation.

Steps

  1. Create the webhook endpoint
  2. Register the webhook
  3. Verify the event origin
  4. Filter events

1. Create the webhook endpoint

To set up a webhook, you need to create a single API endpoint on your server or application that can handle HTTPS POST requests. This endpoint will be automatically triggered whenever there is a change in the status of your payment or refund. By doing this, you can effortlessly receive the webhook notifications and handle them appropriately.

To confirm the processing of a webhook, it's important to respond with a 2xx status code within a reasonable timeframe. It is recommended to send the response within 15 seconds to ensure timely confirmation.

important

This endpoint will be used in both live and test modes, with the event appropriately indicating the mode.

important

If the response does not include a 2xx status code, we will continue sending events. Each message is attempted according to the following schedule, starting each period after the failure of the previous attempt:

  • Immediately
  • Retry after 5 seconds
  • Retry after 5 minutes
  • Retry after 30 minutes
  • Retry after 2 hours
  • Retry after 5 hours
  • Retry after 10 hours
  • Additional retry after 10 hours
// Using Express
app.post("/my/webhook/url", function(req, res) {
const requestBody = req.rawBody;
// Verify and process the received data
res.send(200);
});
caution

To prevent interception of the data, it is important to ensure that the endpoint is secured with HTTPS.

2. Register the webhook

important

To prevent potential issues, we recommend registering only one webhook. If you need to delete any extra webhooks, see here.

To start receiving webhook events on the endpoint you created in Step 1: Create the webhook endpoint, you should register it using our API.

This endpoint requires authenticated access, see here for more details.

https://payments.yoco.com/api/webhooks

Headers

ParameterTypeDescription
Authorization
string
The secret key for your account.

Body

ParameterTypeDescription
name
string
The name you want to give to the webhook you are registering.
url
string
The URL where the webhook events will be sent. Refer to the URL created in Step 1: Create the webhook endpoint.

Sample request

curl --location --request POST 'https://payments.yoco.com/api/webhooks' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <secret-key>' \
--data-raw '{
"name": "my-webhook",
"url": "https://my-application/my/webhook/url"
}'
important

Replace <secret-key> with your secret API integration key. For more information, see here.

Sample response

HTTPS: 201 CREATED
{
"id": "sub_PgrMbbNpWGVc147s6AnHM6aE",
"name": "my-webhook",
"url": "https://my-application/my/webhook/url",
"mode": "live",
"secret": "whsec_M0U0MDI3QjYzMEQ0NTK5NDNCIjVFMENCMDEzNzc1QkE="
}
caution

The secret will be used in Step 3: Verify the event origin. It is important to save this value for future use since it is provided only once.

3. Verify the event origin

Anyone can make a POST request to your event handler. Before processing the event, always verify the origin. For more information on how to mitigate such attacks, see here.

4. Filter events

Your webhook endpoint will receive all payment events processed through our system. However, you will need to filter these events using the Checkout id to ensure you only handle the relevant ones.

Inside the metadata of the webhook event, you'll find a field called checkoutId. Compare this field with your own Checkout id, and if they match, you can proceed to process the event.

important

You can find the Checkout id in the payments flow by referring to Step 1: Create the Checkout.