Get Started

This document explains how to set up a Webhook that will notify you whenever the Event Category you subscribed to is triggered. Once you understand how to set up this Webhook you will know how to set up all Webhooks.

Setting up any Webhook requires you to:

• Create an endpoint on a secure server that can process HTTPS requests.
• Making sure the endpoint is public and can be reached from outside your system.
• Authenticate with Yapily API and receive a Yapily API Token
  • if you don't have a Yapily account then please our Account Setup Guide

If you want to understand better how Webhooks work in Yapily Platform then please check our Webhook Introduction page.

Retrieve Webhook Event Categories

Before we register a Webhook we need to get a list of available Webhook Event Categories.

• Call endpoint GET /webhook/events/categories in order to retrieve all available Event Categories
• Choose the one you want to subscribe to and use them in the Webhook Registration call

Webhook Registration

You can register a Webhook with one or multiple Webhook Event Categories. In order to register a Webhook and to start receiving Webhook Events in your application follow the steps bellow:

• After retrieving all webhook topics, and choosing the ones the webhook should be triggered for
• Build a request using the topics chosen and call POST /webhook/events
• From the successful response of the call get the webhook secret
• Store the webhook secret for further validating the payload signature when receiving events

Retrieving registered webhooks

• Get a Yapily access token
• Call endpoint GET /webhook/events it will return all registered webhooks to your current application

Resetting webhook secret

In situation when the secret gets compromised you have the option to reset it using the API

• Get a Yapily access token
• Reference the webhook id you received when registering the webhook
• Call endpoint POST /webhook/secrets/{webhook_id} it will reset the secret and return the secret in the response

Deleting a webhook

• Get a Yapily access token
• Call endpoint DELETE /webhook/events/{webhook_id} it will return a confirmation that the webhook was deleted

Webhook for Sub-Application

In cases when you are using Application Management for Reseller & Merchants all the steps and limitation remains the same and for each of the request the following changes need to be made:

• Set a sub-application header when executing the http request, with the value being sub-application id
• If the request requires an applicationId field in the request, then the value of the field should be the sub-application id

Validating an Event signature

To protect your server from unauthorised webhook events, all payloads are signed using HMAC algorithm HmacSHA256.

When receiving an event do the following:

• Read the signature from the headers webhook-signature . If you are rotating keys you will receive webhook-rotation-signature too
• Assuming you saved the key provided to you during webhook registration or key rotation
• Read the incoming request body stream directly into a string
• Use the string to generate the HMAC signature using algorithm HmacSHA256
• Compare the hash you got in the headers with the one generated

Webhooks SDK integration

For convenience and to ease the integration on your side we have the following dedicated SDKs ready to be used:

• Java SDK