Setting Up Webhooks

Diffgram offers easy ways to send information to external systems when elevant events occur in the system by configuring actions flows.

Create an Action Flow

The first step to create a notification pipeline for your system events is to create an action flow. You can do this by clicking the "New Flow" button inside the actions menu on the top bar.

716716

Select a Trigger Event

All Action Flow must be started by an event in the system. For this example we will create a webhook POST action when a task is completed. So we will select the event as follows:

12101210

Other events that are available include:

  • Task Creation
  • Task Template Completion
  • File Uploads

Set Aggregation Time

For some cases, you may want to limit the amount of time during which each POST event happens, this can be useful for rate limiting or avoiding high load of requests. To address this problem, we can add aggregation times so Diffgram can accumulate al the events that happened every ceratain amount of time, and then trigger the action. For this example, we will tell Diffgram to trigger the event every 10 minutes.

11831183

Create the Webhooks POST Action

With the trigger events created, you can start adding actions to your flow. The action we will select is an email action, so the task ID and link to the completed task is sent to a user.

As you can see in the picture. The POST payload will be to the url "diffgram.com"

13051305

Secret & Payload of The Webhook.

To prevent other systems from posting. We've added a sha1 signature using the secret you provide in your action flow and the payload of the webhook. This secret will be in the 'X-Hub-Signature' header.
Here's an example of how you might get the key in Python

computed_signature = hmac.new(
codecs.encode(your_secret),
msg=codecs.encode(json.dumps(json_payload_from_the_webhook_request)),
digestmod=hashlib.sha1
).hexdigest()


headers = {
'X-Hub-Signature': computed_signature
}

The payload of the webhook will vary depending on the event. But it will always be a JSON payload with the related object on which the event or events occured. For this case, the payload will contain all the information of the completed task.

You're Done!

That's it! With these simple steps you've setup a pipeline for sending email notifications to your teammates. You can also check how to setup webhooks here