Receiving Webhooks

Introduction

Sometimes you only want to act on a ticket only when a specific event occurs, like when a label is added to it or when a new email comes in. You could poll for any recently updated tickets, but that process would be both slow to react and waste resources when there's no relevant activity.

This is where webhooks can help out. Webhooks are a way for us to send automated notifications to your systems when specific activity happens in your Enchant account. These go out immediately after the event occurs in Enchant with details about the event. It enables you to extend Enchant with custom business flows.

The HTTP Request

We send an HTTP POST to the provided endpoint with a JSON encoded body which describes the event. The request contains the following attributes:

Field	Type	Notes
id	string
account_id	string
account_url	string	Use this when constructing urls for this event
created_at	timestamp	ISO8601 formatted, in UTC
type	string	type of the event
data	object	event specific attributes
actor_type	string
actor_id	string
actor_name	string
model_type	string
model_id	string
model	object	Snapshot of the ticket in the same format as the REST API

A Sample Request

{
  "id": "7f94629",
  "account_id": "a91bb74",
  "account_url": "company.enchant.com",
  "created_at": "2016-10-17T19:52:43Z",
  "type": "ticket.label_added",
  "data": {
    "label_id": "97b0a40",
    "label_name": "High Priority",
    "label_color": "red"
  },
  "actor_type": "user",
  "actor_id": "a91bb75",
  "actor_name": "Michelle Han",
  "model_type": "ticket",
  "model_id": "a52ec86",
  "model": {
    "id": "a52ec86",
    "number": 53249,
    "user_id": "a91bb75",
    "state": "open",
    "subject": "email from customer",
    "label_ids": [
      "97b0a3e",
      "97b0a40"
    ],
    "customer_id": "97b0a43",
    "type": "email",
    "reply_to": "john@smith.com",
    "created_at": "2016-10-14T20:15:46Z",
    ... # truncated
  }
}

The HTTP Response

Your endpoint should return a 200 HTTP status code with HTML body. Any 300, 400 or 500 series response code is considered an error. When errors are encountered, the system will try delivery a few more times before giving up.

Parsing the HTTP Request

In PHP:

$payload = json_decode(file_get_contents('php://input'))

In Ruby:

payload = JSON.parse(request.body.read)

Security

The request also includes a special header Enchant-Signature that is a SHA256 HMAC, signed with a shared secret key. The secret key is provided to you in the Webhooks app settings.

You can validate the request by recalculating the signature and verifying it is the same as the one we provided.

In PHP:

hash_hmac('sha256', $payload, secret_key);

In Ruby:

OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), secret_key, payload)