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 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
note

This is the only API call that would display the webhook secret, you will not be able to retrieve the secret using the API after registration call, please store it if you want to use the webhook signature validation feature

note

An application can register up to 10 webhooks, any further attempts at registering additional webhook will result in a 406 response

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
note

You have the option to reset the secret with a delay, meaning that for the time specified in the reset secret request we will be sending both signatures in the event request giving you time to rotate the secret on your side without any downtime

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

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
note

Do not map it to any structure that may affect the order or structure of the payload before generating the signature

Webhooks SDK integration

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