Webhooks
Webhook Subscriptions is an advanced feature for developers that allows you to be notified of new events via a webhook sent from EASI’R to an endpoint (i.e. HTTP URL) you control.
For example, when a new entity is created, updated or deleted, and a webhook subscription exists for the event in question, EASI'R will send a HTTP POST request to your API endpoint (URL) containing the data of the entity. The data will be in the request body in JSON format.
Data Structure
Webhook requests are always of the type POST.
The webhook data structure is the same as a GET request to the same entity. For example, the data received on a contact_created
webhook is the same as the data received when requesting GET /accounts/:accountId/contacts/:contactId
.
Only data from the point of webhook creation is be transmitted to your endpoint, you cannot receive any data from before the webhook is created.
Headers
Verification Token
You can verify that the webhook is authorized by using the verification token option when creating the webhook. Using the verification token, the webhook HTTP body is hashed using SHA1 along with the token, and the hash is sent in the X-Zebra-Verification-Hash
HTTP header.
Format: sha1(request_body + verification_token)
Request timestamp
The X-Timestamp
header contains the timestamp of when the webhook was generated.
Executing user
On relevant webhooks, the X-Zebra-Executor-User
header contains the ID of the user performing the action.
Error handling
The timeout of a webhook request is 5 seconds.
If your endpoint does not respond with a 200 OK
in time, we will retry 10 times with an exponential delay (pow(2, attempts-1)
in minutes).
Automatic subscription deletion
The webhook subscription is deleted if the endpoint responds with a 410 Gone
status code.
Scopes
Currently, webhooks can be created with two scopes:
global
: (default) Will send webhooks with all data the user has access to. For regular users and team admins, it will generally be entities created in teams they have access to. For admins, it's all entities created by all users across the company.user
: Will only send webhooks with entities the user created themselves.
List of webhook events
Event ID | Sample data | Trigger (API) | Trigger (Frontend Action) |
---|---|---|---|
account_created |
Accounts | POST /accounts |
Creating an account |
account_deleted |
Accounts | DELETE /accounts/:accountId |
Deleting an account |
account_updated |
Accounts | PUT /accounts/:accountId |
Updating an account |
activity_created |
Activities | POST /cases/:case_id/activities |
Creating an activity in a case |
case_created |
Cases | POST /cases |
Creating a case |
case_declined |
Cases | PUT /cases/:caseId/decline |
Declines a case without an activity |
case_deleted |
Cases | DELETE /cases/caseId |
Deleting a case |
case_updated |
Cases | PUT /cases/:caseId |
Updating a case |
contact_created |
Contacts | POST /accounts/:accountId/contacts |
Creating a contact |
contact_deleted |
Contacts | DELETE /accounts/:accountId/contacts/:contactId |
Deleting a contact |
contact_updated |
Contacts | PUT /accounts/:accountId/contacts/:contactId |
Updating a contact |
lead_accepted |
Leads | PUT /leads/:lead_id/accept |
In Opportunities, on lead list |
lead_assigned |
Leads | PUT /leads/:lead_id/assign/:team_id POST /leads |
In Agency, lead was assigned |
lead_created |
Leads | POST /leads |
n/a |
lead_deleted |
Leads | DELETE /leads/:lead_id |
In Agency lead lists |
lead_escalated |
Leads | n/a | n/a |
lead_rejected |
Leads | PUT /leads/:lead_id/reject |
In Opportunities, on lead list |
lead_updated |
Leads | PUT /leads/:lead_id |
n/a |
note_created |
Notes | POST /notes |
Creating a note |
note_deleted |
Notes | DELETE /notes/:note_id |
Deleting a note |
note_updated |
Notes | PUT /notes/:note_id |
Updating a note |
product_created |
Products | POST /products |
Creating a product |
product_deleted |
Products | DELETE /products/:accountId |
Deleting a product |
product_updated |
Products | PUT /products/:accountId |
Updating a product |
task_created |
Activities | POST /cases/:case_id/activities |
Creating an activity with a task |
task_deleted |
Tasks | DELETE /tasks/:task_id |
Deleting a task |
task_updated |
Tasks | PUT /tasks/:task_id |
Updating a task |
team_created |
Teams | POST /teams |
Creating a team |
team_deleted |
Teams | DELETE /teams/:teamID |
Deleting a team |
team_updated |
Teams | PUT /teams/:teamID |
Updating a team |
timeline_event_created |
Timeline Events | POST /cases/:case_id/timeline |
Creating a timeline entry |
user_created |
Users | POST /companies/:company_id/users POST /companies/:company_id/users/:invite_token |
Creating an user |
user_deleted |
Users | DELETE /companies/:company_id/users/:user_id |
Deleting an user |
user_updated |
Users | PUT /companies/:company_id/users/:user_id |
Updating an user |
Get list of webhook events
GET /webhook-events
To get a list of possible events, call the Webhook Events endpoint. The event name is in the form of [entity_type]_[event_type]
.
Response
Status code 200
NOTE: This is a sample list. Query the endpoint to get the whole list of possible webhook events
{
"data": [
{
"id": "10",
"event_name": "account_created"
},
{
"id": "11",
"event_name": "account_updated"
},
{
"id": "12",
"event_name": "account_deleted"
}
]
}
Get all webhook subscriptions
GET /webhooks
Response
Status code 200
{
"data": [
{
"id": 342,
"user_id": 40,
"target_url": "https://example.com/webhook/accounts",
"webhook_event": {
"id": 10,
"event_name": "contact_created"
},
"verification_token": "95DE632D4E07985DAC1F79FF3A042B36F3F2488B",
"created_at": "2016-07-26 14:32:06",
"updated_at": "2016-07-26 14:32:06"
},
{
"id": 2469,
"user_id": 40,
"target_url": "https://example.com/webhook/contacts",
"webhook_event": {
"id": 20,
"event_name": "contact_created"
},
"verification_token": "29644617764732E2201A825B1512202F53C5303",
"created_at": "2016-07-26 14:32:06",
"updated_at": "2016-07-26 14:32:06"
}
]
}
Create a webhook subscription
POST /webhooks
Note: target URLs are considered unique and can only be used once, but you can have multiple different URLs for a single event. (If this is a problem, you can remediate this by adding a query parameter, for example.)
After creating the subscription, the API will respond with an ID you can use to remove the webhook subscription. See the Data Structure section above on more detail on what kind of data your endpoint will receive.
Parameters
target_url
string - The URL the webhook will be sent to. Will always be a POST.webhook_event
string - The name of the event that you are subscribing to.verification_token
string - Custom verification token. See Verification Token.scope
string - The scope of the events to be sents. See Scopes.- default:
global
- default:
Payload
{
"target_url": "http://example.com/api/create-account",
"webhook_event": "account_created",
"scope": "global",
"verification_token": "bnQixQI1CzWix9JQ5SZaH7BBXIExoB"
}
Response
Status code 201
{
"id": 2469,
"user_id": 40,
"target_url": "https://example.com/webhook/contacts",
"webhook_event": {
"id": 20,
"event_name": "contact_created"
},
"verification_token": "29644617764732E2201A825B1512202F53C5303",
"created_at": "2016-07-26 14:32:06",
"updated_at": "2016-07-26 14:32:06"
}
Delete a webhook subscription
DELETE /webhooks/:webhook_id
Response
Status code 204