Learn how to configure a webhook in Hatch to directly hit a downstream system or use Zapier as a "no code" option.
You can use webhooks to send information to systems such as your CRM or dialer. You can use webhooks to send information to almost any external system. For example, you might want to update your CRM to reflect that a contact has opted out of text messages in Hatch.
If you want to learn more about what webhooks are and how you can use them in Hatch, check out Webhook Basics before proceeding.
Configure your webhook
- Navigate to the App Marketplace within Hatch, then click on the Webhooks tab
- Create a new webhook by clicking Add Webhook
- A Webhook Name, Event Trigger, and Endpoint URL are required to save your webhook
- You may attach multiple event triggers to a single webhook
- You may optionally configure headers if required by your endpoint
- Note** the content-type of the Hatch payload will always be application/json and the related header will be automatically added to the request.
- As you select Event Triggers, you will see a preview of the payload that will be sent for that event
- Upon saving, your webhook will be active and ready to start sending new events to your specified URL
Note: You can return to this page at any point to deactivate, edit, or delete your newly created webhook.
Send event via Zapier
If you do not have a developer team to set up a webhook in your downstream system, sending events via Zapier is a good, "no code" option.
- Configure your webhook as described above through step 3
- Open Zapier and create a New Zap
- In the App Event, select Webhooks by Zapier
- In the Event dropdown, select Catch Raw Hook
- Copy the Webhook URL Zapier provides and set that as your Endpoint URL in Hatch
- Finish configuring your webhook, save, and make sure it is set to active
- Trigger a test of your webhook by completing the appropriate action in Hatch depending on your event triggers (e.g., if you are testing an opt-out webhook, find a test Contact and opt them out of communications)
- Return to Zapier and click Test Trigger to see the request details
- The rest of the Zapier setup depends on where you want to send this event data so you should select the appropriate Action based on your destination system
Optional: webhook verification
Hatch uses public key encryption as an extra security measure: Hatch uses a private key to sign the webhooks and a public key has been provided so that you may verify the authenticity of the requests at your endpoint, if you so choose. A single public key is valid for all webhooks within your Hatch Org.
Hatch will send the key hatch-webhook-verification in the header.
Below is an example (in elixir) of how to decode the key:
decoded_signature = Base.decode64!(header_value) :crypto.verify(:eddsa, :none, request_body, decoded_signature, [public_key, :ed25519])
Managing webhooks
In an ideal world, webhooks would be set-it-and-forget-it...but unfortunately, that may not be the case 100% of the time. Here's some tips and resources to assist with testing and managing webhooks in Hatch.
Implementing Multiple Hatch Departments
Most Hatch data, as it relates to contacts, is contained in Hatch within a department (which has 1 or many workspaces attached to it). If your Hatch organization has been separated into more than one department, each with its own set of data, it is important to note that each department also has its own set of integrations-- this includes webhooks.
Deactivate/Reactivate
If you're experiencing some configuration or system issues, it may be useful to temporarily pause your webhook while troubleshooting or making adjustments. Then, you can reactivate it when ready.
Execution History
Hatch will retain execution logs for up to 30 days. These logs are a good place to start if you are noticing any issues, such as missing data. The logs are filterable by date, status, and event type.
In the event that an execution is in a failed status you can view more detail about the attempted request by clicking the arrow on the right.
-
- If Hatch was unable to complete the execution, an Error message will show
- If Hatch was able to complete the execution but unable to successfully deliver the request at the webhook endpoint, the Status Code (400, 401, etc) may clue you into the reason delivery failed
Retries
Hatch will attempt to send the request to the specified endpoint 10 times. After 10 failed attempts, the execution status will be considered officially failed.