Configuring webhooks

The Webhooks Django admin panel has the following settings:

• Description: Add a description for this webhook for reference.

• Event: Choose from the list the event that will trigger the webhook.

• Webhook URL: URL to call. Get it from your webhook processor.

• Enabled: Click to enable the webhook.

• Use WWW form encoding: When enabled, the data will be passed in a web form format. If disabled, data will be passed in JSON format.

Configuring webfilters

The Webfilters Django admin panel has the following settings:

• Description: Add a description for this webhook for reference.

• Event: Choose from the list the event that will trigger the webhook.

• Webhook URL: URL to call. Get it from your webhook processor.

• Enabled: Click to enable the webhook.

• Disable filtering: If enabled, the data passed to the web filter will not be modified even if the response includes any update.

• Disable halting: If enabled, the process will not be interrupted even if the response includes an exception setting.

• Halt on 4xx: Interrupt the process if the call to the URL returns any 4xx error code.

• Redirect on 4xx: Include an URL to redirect in case of a 4xx response, if the event supports redirection.

• Halt on 5xx: Interrupt the process if the call to the URL returns any 5xx error code.

• Redirect on 5xx: Include an URL to redirect in case of a 5xx response, if the event supports redirection.

• Halt on request exception: Interrupt the process if the call to the URL results in a connection error (e.g., timeout).

• Redirect on request exception: Include an URL to redirect in case of a connection error, if the event supports redirection.

• Use WWW form encoding: When enabled, the data will be passed in a web form format. If disabled, data will be passed in JSON format.

Receiving data

Both webhooks and webfilters will trigger POST requests to the configured URL. This request includes in the payload a structure with data relevant to the event that triggered the call. In all cases, the payload will include an event_metadata key including at least the event type and the date and time in UTC format. Other keys included will depend on the event. For example, log in events usually include user and profile keys with details of the user logging in.

If the Use WWW form encoding option is enabled, the data will be passed as plain key-value pairs in form encoding. The structure will be flattened and the key names will be concatenated. E.g., a log event will include user_id, user_email, event_metadata_time, etc.

Responding to webfilters

The webhook processor should respond to a webfilter with a data structure in JSON format and a successful status code (200). The response can be empty or can have one or both of these keys:

• data

• exception

{
    "data": {
        "form_data": {
            "name": "New Name"
        }
    }
}

{
    "exception": {
        "PreventRegistration": "Not allowed to register"
    }
}

Handling multiple events

If you set more than one webhook or webfilter for the same event, all of them will be triggered. The responses of all the webfilters will be combined in one data structure and used to update the objects. If more webfilter processors include data for the same key, the last one will override all the previous.