Webhooks

    Summary: Webhooks are one way that apps can send automated messages or information to other apps. It’s a simple way your Ziflow account can "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" menu - "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.

    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. Key is used to calculate SHA-256 signature passed in 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 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/8652
    • method: 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 added webhook click on its name which open webhook edit mode.
    • Please make sure that you are using raw request body in SHA-256 encryptor.
    • If your webhook URI contains query parameters, their values should be URLencoded for SHA-256 calculation
    • Details of webhook event structure and managing subscriptions using API can be found in API docs.