Yapily Webhooks

Webhooks allows you to receive real-time HTTP notifications of changes happening in the Yapily Platform. For example, we could send you a notification when any of your payment has change status, another use-case is when you are integrating with our async API you will rely on the webhooks notification to understand when the data is ready to be collcted. This prevents you from having to query the Yapily API for changes to objects that may or may not have happened, and helps you avoid reaching your rate limit.

Webhook Event Categories

There are many event triggers in Yapily, such as Payment Status changes and Async API processing status, so whenever you configure a Webhook you must first choose an event category. Since different event categories have different fields, you must then handle each event in a different way. Whenever there's trigger for an event you have subscribed to, we'll send you a notification.

Notifications are sent to you as HTTP POST requests and contain a JSON payload that describes the change. For example, let's say you set up a Payment Status Change Webhook. If one of your app's initiates a Payment, we'd send you a notification regarding a status change for that Payment that would look like this:

Sample Notification

{
  "id": "41285f64-5717-4562-b3fc-2c961236afa6",
  "applicationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "event.category.type",
  "event": {
    "key": "value",
    "metadata": {
      "key": "value"
    }
  },
  "metadata": {
    "tracingId": "6cf5ef06-9f96-4f24-8bab-32ab09128010"
  }
}

• id - the webhook id used to trigger this event
• applicationId - the application id that registered this webhook
• type - event type that you've subscribed to
• event - event key will contain the actual event change that has happened, for more details on what can it hold please consult the documentation page of the product you are integrating with
  • metadata - (OPTIONAL) webhook metadata if any was registered with the webhook
• metadata - yapily event metadata

Webhook Metadata

When registering a Webhook, the API will allow you to specify a metadata field the content of which is totally in your control. You can specify any key : value pairs in there, and we will send you all that data back on every Webhook Event where your subscription is being called.

Your Callback Server

To enhance the reliability and conversion rates of the events we deliver to your service, please ensure adherence to the guidelines bellow

Public URL

Ensure that your service callback endpoint is on a public URL so that we can make these requests successfully

HTTPS Handling

Webhooks are sent using HTTPS, so your server must be able to receive and process HTTPS requests, and it must have a valid TLS/SSL certificate installed. Self-signed certificates are not supported.

Return 200 OK response

The endpoint must return a 200 OK response, which tells the Yapily Platform the event has been received and does not need to be resent. Normally, you will not send this response until you have completed processing the notification.

Respond to Event Notifications

Your endpoint should respond to all notifications:

• with a 200 OK HTTPS response
• within 1 or less seconds

Setup

To use Webhooks, you will need to set up an endpoint on a secure (HTTPS) server, then add and configure the Webhooks product on your end. The rest of these documents explain how to complete these steps.

Ready? Let's get started!