Webhooks

Overview

Webhooks allows you to subscribe to changes and be notified of these changes as and when they occur. Webhooks are basically an easy way to receive notification of changes (Events) via an HTTP POST instead of polling for them. For services accessible via HTTP this is vastly more convenient and efficient.

Ziflow currently sends one Event object per POST. We will later on extend this and send arrays of Event objects per POST which should be handled by the target.

Webhooks Setup

Webhook Subscriptions tell Ziflow what a particular app would like to get notified about. We currently support the following subscription types:

  • Proof events
    • Created
    • Processed (succeeded or failed)
    • Deleted
    • Updated
    • Status change
    • All comment events
    • All decisions events

Managing Subscriptions via the UI

You can create and manage webhooks via the UI:

  1. Log in to your Ziflow account and ensure you have Admin permissions
  2. Click on your Avatar (top right) -> Manage account -> Webhooks

Here you’ll be able to add, remove, update and activate/deactivate webhooks.

Managing Subscriptions via the API

The following endpoints allow you to create Subscriptions. The UI is the recommended way to manage your subscriptions.

Subscriptions have the following fields:

Field

Description

Read-only

id

Unique ID of a subscription

subscription-types

{

'proof': {

'all': true,

'created': true,

'processed': true,

'changed': true,

'deleted': true,

'status_change': true,

'comment': true,

'decision': true

}

}

 

name

The name for your subscription

 

target

The target for your subscription - must be a valid URL

 

active

true / false

Whether or not the subscription is active and trigger notifications

Default: false

 

created at

When this subscription was created

 

 

 

Events desciption

Each event object is sent in "events" array - see sample JSON after tables.

Event object structure:

Field Description
event_id Event id
webhook_id Webhook id
contact Contact object
event_type Always 'proof'
proof_event See detailed description in table below
created_at Date and time '2018-06-13T04:50:35.521Z'
attempt_number Attempt number
attempt_at Date and time '2018-06-13T04:50:35.521Z'

Proof event object structure description:

Field Description
proof_id Proof id
version_previous_id

Previous version id

action 'created' / 'updated' / 'processed' / 'failed' / 'comment' / 'decision' / 'status' / 'deleted'
comment_event

If action 'comment', object has structure:

{

"comment_id": commentId,

"parent_id": Id of comment if reply

"action" : 'created' or 'changed'

}

Default: null

decision_event

If action 'decision', object has structure:

{

"reviewer_id": if of reviewer making decision

}

Default: null

Sample event JSON
JSON has action 'comment' but contains also sample decision_event structure to show it - normally decision_event would be null in this case.

[


{


"events": [

{

"event_id": "48219ea8-5b74-4c50-9dc2-11b01d218fbd",

"webhook_id": "d8bb19a0-198c-4ec8-b569-c4166bf37ef2",

"contact": {

"id": "43d6beaa-7e00-45a7-b0a7-3ec05f8cae10",

"type": "user",

"first_name": "User",

"last_name": "Name",

"email": "name@domain.com",

"roles": [

"user",

"manager"

],

"phone": null,

"company": "Awesome Company",

"tenant": {

"tenant_id": "f9163323-fcda-4c95-b129-3cdb6f8d4a71",

"subdomain": "yourdomain",

"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": null,

"action": "comment",

"comment_event": {

"comment_id": "e92a3091-d5d0-4d89-89bf-3b93a468bf97",

"parent_id": null,

"action": "created"

},

"decision_event": {

"reviewer_id": "af1f6f4f-8b71-4351-b9be-4007aad62266"

}

},

"created_at": "2018-06-13T04:50:35.521Z",

"attempt_number": 0,

"attempt_at": "2018-06-13T04:50:35.664Z"

}

]

}

]

 

Create a Subscription

Method Details
HTTP methods POST
Response format json
Requires authentication Yes
Rate limited Yes

POST /v1/webhooks

Creates a new subscription with a simple HTTP POST.

Returns subscription object.

Can be performed only by user with Admin rights.

Required parameters How to use Description
Admin API Token apikey=[key] query parameter Used to authenticate the request
subscription-types Used in the request body  At least one type must be true
name Used in the request body  
target Used in the request body - must be a valid URL  
Optional parameters How to use Description
active Used in the request body Default is false
Sample POST webhook body

{

"name": "Webhook name",

"target": "https://youraddress.com",

"active": true,

"subscription_types": {

"proof": {

"all": false,

"created": true,

"processed": true,

"changed": true,

"deleted": false,

"status-change": false,

"comment": true,

"decision": false

}

}

}

 

Delete Subscription

Method Details
HTTP methods DELETE
Response format json
Requires authentication Yes
Rate limited Yes

DELETE /v1/webhooks/{subscription_id}

Returns empty data record.

Can be performed only by user with Admin rights.

 Required parameters  How to use  Description
 Admin API Token  apikey=[key] query parameter  Used to authenticate the request
 Subscription ID  Used in the request URL (see above)