Webhooks

General

If you want to react to changes happening in Makaira you can subscribe to our webhook. Whenever one of the supported entities is created, changed or deleted, we send a call to an endpoint of your choice.

Usage

You can use the webhook to trigger external processes in your systems outside of Makaira or to sync data from one Makaira installation to another.

Setup of Webhooks

You can set up the webhook yourself. All it takes is storing your delivery URL in the configuration of the instance you want to receive calls from:

curl --location --request PUT 'https://<yoursubdomain>.makaira.io/configuration' \
--header 'Content-Type: application/json' \
--header 'X-Makaira-Instance: <instance name>' \
--header 'X-Makaira-Nonce: <nonce of request>' \
--header 'X-Makaira-Hash: <signature of request>' \
--data-raw '{
    "webhookConfig": {
        "url": "https://<your webhook delivery URL>"
    }
}'

The same call is used to change the delivery URL later on. Setting an empty URL disables the webhook again.

Please note that there is one delivery URL per instance, and all entities are subscribed by default. As soon as you set a URL you will receive calls for every entity type listed below, not only for the one you are interested in. Use the type field of the payload to filter for the entities you care about.

If you want us to narrow down the list of delivered entities, please contact our support and let us know your Makaira domain, the instance and which entities should be delivered.

Delivered Entity Types

Pages trigger a webhook call no matter whether they were changed in the Page Editor or through the landing page API — both use the same code path internally. Autosaves and revisions do not trigger a call, only the saved page itself does.

Body of a Webhook Call

We are delivering a POST Call to your endpoint with the following body

{
    "customer": "your-subdomain",
    "instance": "stage",
    "type": "landingpage",
    "ids": ["5"],
    "action": "create"
}

• customer is the subdomain of your makaira installation
• instance is the instance name where the Webhook is set up
• type tells you what type of entity was changed, see the table above
• ids is a list of entity ids that have been changed (e.g. in a bulk delete there could be multiple ids in this array)
• action tells you which action was executed in the change (one of create, update, remove; deleting pages sends delete)

The payload contains metadata only, not the content of the changed entity. To get the entity itself, request it from the corresponding API endpoint after receiving the call.

Delivery

• Calls are delivered as a POST with Content-Type: application/json.
• Delivery happens synchronously while the change is being saved in Makaira. Please answer quickly with a 2xx status and do the actual work asynchronously on your side, otherwise you slow down editing in Makaira.
• There is no retry. If your endpoint is unreachable or answers with an error, the call is logged on our side and dropped.
• Requests are not signed. If your endpoint needs to be protected, use a hard to guess URL or a token as part of the URL.