WebMini API

Webhooks

Introduction

Webhooks allow your application to get notified whenever a certain event happens on a WebMini service. Our system will send a HTTP POST call to the URL you configured for the webhook. The call will contain a JSON payload providing all details about the specific event.

Managing Webhooks Manually

WebMini provides an easy-to-user interface to manually add, edit, and delete webhooks:

  1. Go to the Webhooks page in your user account.
  2. Click on Add Webhook.
  3. Choose the WebMini service account you would like to create the webhook for.
  4. Choose the event that should trigger a webhook call, and enter the target URL of the webhook.
  5. Once you added the webhook, you will see a page that tells you your Payload HMAC Key. Do not share the key with anyone!

Managing Webhooks via API

Webhooks can also be created and deleted using the WebMini API. If you want that your application is notified of events in a user’s account, we recommend creating an OAuth2 application, let the user authenticate via OAuth2, and then create a webhook in that user’s account for the required event(s) using the API calls below.

You can find all details on how to create, manage, and delete webhooks with the API on the Global API Functions page.

Events

All events that a webhook can be created for are listed on their specific service API documentation page.

Delivery Headers

HTTP requests made to your webhook’s configured URL endpoint will contain several special headers:

Header Description
X-WebMini-Event Name of the event that triggered this webhook call.
X-WebMini-Signature HMAC hex digest of the payload, using the hook’s secret as the key. See below for details.

Payload Signature

Each webhook contains the X-WebMini-Signature header. The value of this header is the HMAC hex digest of the webhook body, i.e. the JSON-encoded payload. The webhook’s secret that was shown to you when creating the header will be used as the secret key of the HMAC digest.

The HMAC hash will be prepended with sha1= indicating the algorithm used for the hash.

We highly recommend to always verify each payload delivered to your system by calculating the HMAC hash in your application and making sure it matches the signature provided in the header.

Automatic Removal of Invalid Webhooks

WebMini automatically curates its active webhooks based on the HTTP reponse your server gives when receiving a webhook from WebMini:

HTTP Code Resulting Action By WebMini
200 OK Keep webhook active. Future events will trigger the webhook again.
410 Gone Immediately deactivate and remove webhook.
Any Other WebMini will assume that something went wrong. Occasional errors will not deactivate the webhook, but excessive errors such as  multiple 4xx or 5xx failures may result in deactivation and/or deletion of the webhook.