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:
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.
Webhook name - give a name to the webhook.
Webhook URL - insert 3rd party URL address to which Ziflow data will be sent.
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 "\".
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:
Once you add the endpoint, please remember to activate it since newly added webhooks are disabled by default.
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:
key:
1-app-key-34/8652method: POST
webhook URI: https://some.endpoint.com?param=value/something
encoded webhook URI: https://some.endpoint.com?param=value%2Fsomething
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.