Receiving Webhooks


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:

account_urlstringUse this when constructing urls for this event
created_attimestampISO8601 formatted, in UTC
typestringtype of the event
dataobjectevent specific attributes
modelobjectSnapshot of the ticket in the same format as the REST API

A Sample Request

  "id": "7f94629",
  "account_id": "a91bb74",
  "account_url": "",
  "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": [
    "customer_id": "97b0a43",
    "type": "email",
    "reply_to": "",
    "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


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

In Ruby:

payload = JSON.parse(


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.


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

In Ruby:

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