Webhooks

Connect Ziflow with your web applications via the Ziflow API.

Updated over a week ago

Summary: Webhooks are one way that apps can send automated messages or information to other apps. It’s a simple way for your Ziflow account to "speak" with other online applications and get notified automatically when something new happens.

Available on all Ziflow Editions. Only users with Admin rights can set and read Ziflow webhooks.

Where is the feature setup? Go to Settings > API settings > Webhooks as shown below:

Webhook settings in Ziflow

How does it work?

Click on the Add endpoint button, and you will be presented with a new window where webhook details need to be filled in.

Configuring webhooks in Ziflow

  1. Webhook name - give a name to the webhook.

  2. Webhook URL - insert 3rd party URL address to which Ziflow data will be sent.

  3. Webhook signature key - Ziflow can optionally sign the webhook events it sends to your endpoints by including a signature in each event’s Ziflow-Signature header. This allows you to verify that the events were sent by Ziflow, not by a third party. The key is used to calculate the SHA-256 signature passed in the webhook header "x-ziflow-signature" for each event. You can either use a key generated by Ziflow or provide your own. It should be max 255 chars, alphanumerical with "-" and "\".

  4. Filter event - select the events that are supposed to be sent from Ziflow to the 3rd party application. You can choose to send all events or just some of them:

Different events available when settings up a webhook in Ziflow

Once you add the endpoint, please remember to activate it since newly added webhooks are disabled by default.

Activating added webhook in Ziflow

Webhook signature key

The SHA-256 signature is being generated from:

  • webhook_siganture_key

  • HTTP method

  • URI

  • Raw request body

<APPKey><HTTPMethod><WebhookUri><RequestBody>

Sample raw json/raw body to put in SHA-256 encryptor:

1-app-key-34/8652POSThttps://some.endpoint.com?param=value%2Fsomething{"events":[{"event_id":"48219ea8-5b74-4c50-9dc2-11b01d218fbd","webhook_id":"d8bb19a0-198c-4ec8-b569-c4166bf37ef2","contact":{"id":"ec2b4aee-42b6-42f8-92cd-264d1c9d4d0c","type":"user","first_name":"User","last_name":"Name","email":"name@domain.com","roles":["manager"],"phone":"+4412345678911","company":"ABC Inc","tenant":{"tenant_id":"ab6d3631-b96b-49da-92c4-6b0af7fc1b48","subdomain":"your-subdomain","company_name":"Awesome Company"},"verified":true,"blocked":false,"timezone":"Europe/London"},"event_type":"proof","proof_event":{"proof_id":"35b26dd9-4e8c-4fc5-a9ec-c68c8fb2e086","version_previous_id":"79b26dd9-6e8c-4fc5-bg9e-c68c8fb4g254","action":"comment","pass_through_value":"1f1782e1","comment_event":{"comment_id":"e92a3091-d5d0-4d89-89bf-3b93a468bf97","parent_id":"gb6f6f4f-8b71-4351-b9be-4007aad67528","reviewer_id":"b17b7fc0-d4a4-4d68-a69c-0a2867b59028","action":"created","text":"Comment text","like":false,"labels":[{"id":"gb6f6f4f-8b71-4351-b9be-4007aad67528","label":"To do"}],"resolved":true},"decision_event":null,"status_event":null,"opened_event":null,"summary":null,"completed_event":null,"mention_event":null},"created_at":"2018-06-13T04:50:35.521Z","attempt_number":1,"attempt_at":"2018-06-13T04:50:35.664Z"}]}

Additional information:

  • If you want to edit an added webhook, click on its name, which opens webhook edit mode.

  • Please ensure you are using the raw request body in the SHA-256 encryptor.

  • If your webhook URI contains query parameters, their values should be URL-encoded for SHA-256 calculation.

  • The webhook event structure and managing subscriptions using API can be found in API docs.

Did this answer your question?