Creating and Managing Webhooks

Developers
1

Introduction

Welcome to the Empress developer guide. This guide focuses on a key feature in Empress: Webhooks. Webhooks are user-defined HTTP callbacks that enable you to create programs that respond to document events. This functionality is critical in creating a versatile and connected system architecture, allowing developers to configure interactions between different sites or applications.

Understanding Webhooks

Webhooks serve as crucial interfaces between different parts of a system or between different systems altogether. By defining the DocType and the event that triggers the webhook, you can create a system that responds to changes in one part of the system by executing actions in another. For example, an update in a Quotation DocType could trigger a webhook that sends the updated data to another site or application.

Configuring a Webhook

Webhooks are easy to set up in Empress. Here’s a step-by-step guide:

  1. Navigate to Integrations > Webhook > Webhook.
  2. Select the DocType for which the webhook needs to be triggered (e.g. Quotation).
  3. Select the Doc Event that will trigger the webhook (e.g. on_update).
  4. Optionally, set additional document conditions to trigger the webhook for specific scenarios.
  5. Enter a valid request URL that will receive the webhook data.
  6. Select the Request Method. POST is the default method.
  7. Optionally, add HTTP headers to the request (useful for sending an API key, if required).

You can disable a webhook at any time by unchecking the Enabled checkbox. Only enabled webhooks are triggered.

Data Structure and Security

Webhooks can be configured for form-based or JSON-based request structures. For form-based structures, you can select fields from the document in the table that uses the fieldname as the key. For JSON-based structures, you can insert fields from the document using jinja templating (ensure to wrap your fields with double-quotes).

Empress also allows you to add security to your webhook requests through the “Webhook Secret” feature. When enabled, an additional header (X-Empress-Webhook-Signature) is added to the request before it’s sent out. The value of this header is generated from the secret as a base64-encoded HMAC-SHA256 hash of the payload.

Webhook Examples and Logs

Empress maintains a comprehensive log of webhook requests. For every successful request, a webhook request log is created with all the relevant details. This log serves as a crucial debugging tool for developers, helping you trace and understand the data flow through your webhooks.

Conclusion

Webhooks represent a powerful feature in Empress, allowing developers to create highly customized and interconnected systems. By understanding and making the most of this feature, you can create dynamic software solutions that respond swiftly to changes in your data.