Skip to main content

Webhooks

This page covers features available only from 2.3.0

Webhooks are a way to make Izanami call a provided URL when a feature is modified.

Given URL is called with new activation status for modified feature.

This is useful if you want to execute some specific code on feature activation, or if you want to keep your feature in sync with an external system that can't perform HTTP call to Izanami.

Webhook creation

To create a webhook, go to the webhook screen of your tenant and click the "Create new webhook" button.

This form allows configuring your webhook :

  • url indicates which URL should be call when a feature is updated
  • name and description allows describing what your hook is and what it's doing
  • headers allows specifying custom HTTPs headers to pass while calling webhook
  • features and projects specify hook scope : hook will be called only when a listed feature (or a feature of one of the listed projects) is modified
  • context and user allows specifying context and user for which activation will be recomputed
  • custom body allows transforming sent body (using a handlebars template). This is especially useful when integrating with external services, such as messaging systems.

When enabling custom body, a template editor appears on the screen.

This editor allows indicating handlebars template to apply to "original" events in order to generate event to send.

Left part of the screen allows to select or edit and "original" event. Right part allows typing your template.

Bottom button allows applying your template on selected (or edited) event, and will display the result. It's useful to make sure that your template work as expected.

Webhook call

Webhook is called for a feature in scope when:

  • it's created
  • it's deleted
  • its enabling is modified
  • its activation conditions are modified
  • an overload is created / updated / deleted for it
  • its name changes (we need to call webhook since user based activation condition rely on name)

Resilience

Izanami offers some guarantees for webhook resilience.

If webhook call timeout or if remote server respond with an error code, Izanami will retry the call several times, with an increased interval between calls. To do so, Izanami will use exponential backoff algorithm elements of this algorithm can be configured, see dedicated configuration section for details.

If Izanami instance is shut down (or crashes) while making an initial or retry call, webhook call will be retried after some times either when Izanami instances restart or by another instance if Izanami has multiple instances.

Rights

Each hook has a dedicated right section, as for keys, tenants or projects, users can have 3 right levels on hooks :

Read hook informationRead hook informationCreate/update webhookDelete webhook
Read
Write
Admin (or tenant/global admin)