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_updated Accounts PUT /accounts/:accountId Updating an account
account_deleted Accounts DELETE /accounts/:accountId Deleting an account
contact_created Contacts POST /accounts/:accountId/contacts Creating a contact
contact_updated Contacts PUT /accounts/:accountId/contacts/:contactId Updating a contact
contact_deleted Contacts DELETE /accounts/:accountId/contacts/:contactId Deleting a contact
product_created Products POST /products Creating a product
product_updated Products PUT /products/:accountId Updating a product
product_deleted Products DELETE /products/:accountId Deleting a product
activity_created Activities POST /cases/:case_id/activities Creating an activity in a case
lead_created Leads POST /leads n/a
lead_assigned Leads PUT /leads/:lead_id/assign/:team_id
POST /leads
In Agency, lead was assigned
lead_rejected Leads PUT /leads/:lead_id/reject In Opportunities, on lead list
lead_accepted Leads PUT /leads/:lead_id/accept In Opportunities, on lead list
lead_escalated Leads n/a n/a
lead_called Leads PUT /leads/:lead_id/call In Agency, in escalated leads
lead_revoked Leads n/a n/a
lead_updated Leads PUT /leads/:lead_id n/a
lead_deleted Leads DELETE /leads/:lead_id In Agency lead lists
task_created Activities POST /cases/:case_id/activities Creating an activity with a task
user_created Users POST /companies/:company_id/users
POST /companies/:company_id/users/:invite_token
Creating an user
user_updated Users PUT /companies/:company_id/users/:user_id Updating an user
user_deleted Users DELETE /companies/:company_id/users/:user_id Deleting 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

Deprecated parameters

  • event deprecated in favor of webhook_event
    • Removal: 2018/04/01

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