Webhooks

Webhooks are your back office's gateway to the outside world. They allow you to interact with other applications via an event system. Just like your back office API, it's an essential part of building your workflows.

Composition

A webhook endpoint is composed of a unique URL, a method, a secret key, and a set of events.

Possible request methods are:

• DELETE
• GET
• PATCH
• POST
• PUT

The events are the set of actions that will trigger a call to the URL of the webhook, for example, add a user, edit a task, delete a file etc.

Requests

Every event on your back office triggers a webhook request if the webhook has been configured. A webhook request contains several pieces of information from the back office:

• the content representing the resource in JSON format
• the event in the format resource.action, e.g. user.create
• the secret key in the x-backoffice-signature request header

Here's an example of content sent by your webhook:

{
  "event": "user.create",
  "payload": {
    "id": "6fb779a9-d615-4d1b-be5f-78421977acb2",
    "email": "[email protected]"
  }
}

Once the request is made, its result is persisted via two fields:

• the response body which contains the request response in JSON format
• the response code which contains the response code of the request

If the request fails, it is possible to retry it.

Security

⚠️

In order to guarantee the security of your webhook, it is advisable to implement these few actions:

• Use the POST method for your webhooks
• Use the HTTPS protocol for the URL of your webhooks
• Authenticate the secret key via the x-backoffice-signature header

Case study

Let's say you want to send an email every time a task is completed. To do this, you'll combine webhooks with an automation service such as Zapier. Simply, you create a new zap on Zapier in two steps:

1. Catch hook
2. Send email

You then get your webhook endpoint URL: https://hooks.zapier.com/hooks/catch/1.

All you need to do is create a new webhook with the following parameters:

• URL: https://hooks.zapier.com/hooks/catch/1
• Method: POST
• Events: Complete Task

And voila! 🎉 Your automation was set up in two simple steps.