We can send notifications about the progress of certain async processes to a URL of your choice. You can configure the webhook URL in the Heron dashboard by navigating to the “Settings” tab on the left menu bar.

This is an example structure of our webhooks:

webhook.json
{
	"topic": "end_user.processed",
	"created": "2021-05-20T09:23:53+00:00",
	"data": {
		"heron_id": "eus_Eqio3Y4dhyNiMphrXwG58p",
		"end_user_id": "myenduser",
		"status": "processed"
	},
	"meta": null
}

  • topic is the topic of this webhook in the format <resource>.<event>. Currently we support webhooks for the following topics:

  • created is the UTC datetime when the webhook was sent, in ISO format.

  • data contains the data of the resource which relates to this event.

  • meta (optional) contains further information about the event.

For a full list of webhook topics we support, use the GET /webhooks/topics endpoint.

​
Verification

We send a Heron-Signature header in every webhook request. This header is a base64-encoded HMAC SHA256 digest of your shared secret and the webhook’s payload.

To verify the webhook was sent by us, calculate the digital signature using the same algorithm and compare it to the Heron-Signature header.

Here is an example of how to calculate the signature in Python:

import base64
import hashlib
import hmac
import json

secret = "sec_..." # shared secret, *not* your API credentials
data = {"topic": "end_user.processed", ...}

message = json.dumps(data, separators=(",", ":"))

dig = hmac.new(
    secret.encode("utf-8"),
    msg=message.encode("utf-8"),
    digestmod=hashlib.sha256,
).digest()

signature = base64.b64encode(dig).decode()

And in JavaScript (Node):

const crypto = require('crypto')

const secret = 'sec_...'
const data = {"topic": "end_user.processed", ...}

const signature = crypto
  .createHmac('sha256', secret)
  .update(JSON.stringify(data))
  .digest('base64')

​
Slack webhooks integration

If you don’t want to build a system for receiving webhooks, we support Slack Incoming Webhooks URLs when you create a webhook. This allows you to fire alerts generated by Heron Data (e.g. a rule has been broken) directly into a Slack channel for you to take action.

Follow these steps:

  1. Follow the Slack Incoming Webhook Documentation.
  2. Slack will create a webhook url of the format https://hooks.slack.com/services.... for you. Copy this url.
  3. Open the Heron Data dashboard, navigate to the Settings page on the left, and go to Webhooks.
  4. Press Add webhook and pick the appropriate topic. Most commonly, you’ll want to fire a Slack alert when a rule has been broken. The webhook topic for this is end_user.review_required.
  5. Press Create webhook.
  6. To test the Slack webhook, re-process a company that breaks a rule. This will now fire a Slack alert!