accounts/webhooks

Supported methods

List methods:GETPOST

Instance methods:GETDELETEPOST

Webhooks list

GET: Listing of WebHook configured for an account

Response body

[
  {
    "callback_url": stringYour callback URL to which we'll POST message data,
    "failure_notif_url": stringYour callback URL for failure notifications,
    "active": booleanWhether this webhook is currently applied to new messages we find in the account or not,
    "failure": booleantrue means we're having issues connecting to the account and gave up after a couple retries. The failure_notif_url is called when a webhook's failure property becomes true.,
    "sync_period": stringMaximum time allowed between the event happening in the mailbox and your callback_url being called,
    "webhook_id": stringId of the webhook,
    filter_*: stringValue of a filter assigned to this webhook when created,
    ...
  },
  ...
]

POST: Create a new WebHook on an account

Parameters

name	type	description
required:
callback_url	string (url)	A valid URL Context.IO calls when a matching message is found. The callback URL is called with an HTTP POST with message information in request body, see receiving webhook callbacks below.
failure_notif_url	string (url)	A valid URL Context.IO calls if the WebHooks fails and will no longer be active. That may happen if, for example, the server becomes unreachable or if it closes an IDLE connection and we can't re-establish it. The callback URL is called with an HTTP POST with more information in request body, see receiving failure notifications below.
optional:
filter_to	string	Check for new messages sent to a given name or email address.
filter_from	string	Check for new messages received from a given name or email address.
filter_cc	string	Check for new messages where a given name or email address is cc'ed
filter_subject	string	Check for new messages with a subject matching a given string or regular expresion
filter_thread	string	Check for new messages in a given thread. Value can be a gmail_thread_id or the email_message_id or message_id of an existing message currently in the thread.
filter_new_important	string	Check for new messages automatically tagged as important by the Gmail Priority Inbox algorithm. To trace all messages marked as important (including those manually set by the user), use filter_folder_added with value \Important. Note the leading back-slash character in the value, it is required to keep this specific to Gmail Priority Inbox. Otherwise any message placed in a folder called "Important" would trigger the WebHook.
filter_file_name	string	Check for new messages where a file whose name matches the given string is attached. Supports wildcards and regular expressions like the file_name parameter of the files list call.
filter_file_revisions	string	Check for new message where a new revision of a given file is attached. The value should be a file_id, see getting file revisions for more info.
filter_folder_added	string	Check for messages filed in a given folder. On Gmail, this is equivalent to having a label applied to a message. The value should be the complete name (including parents if applicable) of the folder you want to track.
filter_folder_removed	string	Check for messages removed from a given folder. On Gmail, this is equivalent to having a label removed from a message. The value should be the complete name (including parents if applicable) of the folder you want to track.
sync_period	string	Desired maximum delay between the moment the email comes in the user's mailbox and the time we call the callback_url. To have your callback_url called as soon as possible (typically, this means within a minute after the event occurred in the mailbox), set this parameter to immediate or 0. Other possible values are 30m, 1h, 4h, 12h and 24h (default) meaning 30 minutes, 1 hour, 4 hours, 12 hours and 24 hours respectively.

Response body

{
  "success": booleanWhether the operation worked,
  "webhook_id": stringId of the webhook that has been created,
  "resource_url": stringComplete URL of the new webhook
}

WebHooks instance

GET: Properties of a given WebHook

Response body

{
  "callback_url": stringYour callback URL to which we'll POST message data,
  "failure_notif_url": stringYour callback URL for failure notifications,
  "active": booleanWhether this webhook is currently applied to new messages we find in the account or not,
  "failure": booleantrue means we're having issues connecting to the account and gave up after a couple retries. The failure_notif_url is called when a webhook's failure property becomes true.,
  "sync_period": stringMaximum time allowed between the event happening in the mailbox and your callback_url being called,
  "webhook_id": stringId of the webhook,
  filter_*: stringValue of a filter assigned to this webhook when created,
  ...
}

POST: Change properties of a given WebHook

The only property of a WebHook that can be changed is it's active property. If you want to change the filters or callback urls, delete it and create a new one.

Changing the active property can be useful in two cases:

Pause/resume WebHooks

If your application needs up-to-date information when users are logged in the best option is to keep a WebHook with no filters on that account that will be resumed (setting active to 1) when the user logs in and paused (setting active to 0) when the user logs out of your app.

Acting upon a failure notification

If a WebHook fails, your failure_notif_url is called (see creating a WebHook) an its failure property becomes true. Make a POST request on that WebHook with the active parameter set to 1 to reset it.

Parameters

name	type	description
required:
active	integer	The active property of a WebHook allows you to pause (set to 0) or resume (set to 1) it.

Response body

{
  "success": booleanWhether modification succeeded
}

DELETE: Cancel a WebHook

Receiving WebHook callbacks

When an event matching the filters set for your webhook occurs in the mailbox, we do an HTTP POST request to your callback_url.

Request body

The body of this request is a JSON object which includes information about the webhook, a token and signature to validate its origin and information about the message that matched your webhook:

{
    "account_id": stringAccount who owns the webhook,
    "webhook_id": stringId of the webhook that has been triggered,
    "timestamp": numberServer time for the request as a unix timestamp,
    "message_data": {
      "email_message_id": stringValue of RFC-822 Message-ID header,
      "addresses": objectEmail addresses and names of sender and recipients (more details),
      "person_info": objectAdditional info about contacts on this message (more details),
      "message_id": stringUnique and persistent id assigned by Context.IO to the message,
      "gmail_message_id": stringMessage id assigned by Gmail (only present if source is a Gmail account),
      "gmail_thread_id": stringThread id assigned by Gmail (only present if source is a Gmail account),
      "files": [
        {
          "size": numberSize of the attachment in bytes,
          "type": stringValue of Content-type header for the attachment,
          "file_name": stringFull name of the file attached,
          "file_name_structure": arrayName of the file broken down in semantic parts (more details),
          "body_section": numberIdentifies MIME body part the attachment can be found in,
          "file_id": stringUnique and persistent id assigned by Context.IO to the file,
          "is_embedded": booleanIndicates whether this file is an object embedded in the message or not,
          "content_disposition": stringValue of the Content-Disposition header of the MIME part containing this file, if specified. Typically 'inline' or 'attachment',
          "content_id": stringIf this file is an embedded object, this is the value of the Content-Id header of the MIME part containing this file
        },
        ...
      ],
      "date": numberUnix timestamp of message date,
      "date_indexed": numberTime this message was first seen by Context.IO (unix timestamp),
      "subject": stringSubject of the message,
      "folders": arrayList of folders (or Gmail labels) this message is found in,
      "sources": [
        {
          "label": stringLabel of the source containing this message,
          "resource_url": stringComplete URL of the source
        },
        ...
      ]
    },
    "token": stringRandom string used to calculate signature,
    "signature": stringHMAC-SHA256 hash of the timestamp and token with your Context.IO secret as the hashing key
}

Authentifying requests to your callback URL

You can validate that a request to your callback URL is a valid request from Context.IO using the combination of the timestamp, token and signature properties in the body. The signature is the HMAC-SHA256 hash of the string formed by concatenating the timestamp and token using your Context.IO OAuth secret as the hashing key.

Here's an example in PHP of how you would authentify a request to your callback url:

<?php
// decode request body
$body = json_decode(file_get_contents('php://input'), true);

if ($body['signature'] == hash_hmac('sha256', $body['timestamp'].$body['token'], YOUR_CONTEXTIO_CONSUMER_SECRET)) {  
  // request is authentified
}
else {  
  // invalid request, you can ignore it 
}
?>

Issues with Apache and mod_security

The mod_security module for Apache decided application/json is an exotic Content-type for the body of a POST request and rejects them by default, typically with a 406 status code. To avoid having Apache reject WebHook callbacks, you need to either change default mod_security configs or disable it for your domain.

Accepting POST requests with application/json Content-type in mod_security

Change:

SecFilterSelective HTTP_Content-Type \
"!(^$|^application/x-www-form-urlencoded$|^multipart/form-data;)" 

to:

SecFilterSelective HTTP_Content-Type \
"!(^$|^application/x-www-form-urlencoded$|^multipart/form-data;|^application/json$)" 

[reference]

Accepting POST requests with application/json Content-type in mod_security 2

Change:

SecRule HTTP_Content-Type \
"!(^application/x-www-form-urlencoded|^multipart/form-data;).*$"

to:

SecRule HTTP_Content-Type \
"!(^application/x-www-form-urlencoded|^multipart/form-data;|^application/json).*$"

[reference]

Receiving failure notifications

If we no longer can monitor the mailbox for events matching the WebHook, we do an HTTP POST request to your failure_notif_url and change the failure property of the webhook to true. Examples of when this may happen are: the mail server goes down, the account becomes unreachable or the folders you're monitoring no longer exist.

Request body

The body of this request is a JSON object which includes information about the webhook, a token and signature to validate its origin and information about the message that matched your webhook:

{
    "account_id": stringAccount who owns the webhook,
    "webhook_id": stringId of the webhook that has been triggered,
    "timestamp": numberServer time for the request as a unix timestamp,
    "data": stringError message that gives more information about the cause of failure,
    "token": stringRandom string used to calculate signature,
    "signature": stringHMAC-SHA256 hash of the timestamp and token with your Context.IO secret as the hashing key
}

Authentifying requests to your callback URL

You can validate that a request to your callback URL is a valid request from Context.IO using the combination of the timestamp, token and signature properties in the body. The signature is the HMAC-SHA256 hash of the string formed by concatenating the timestamp and token using your Context.IO OAuth secret as the hashing key.

See receiving webhook callbacks above for an example.

Restoring a WebHook

Every WebHook for which this failure notification callback is made will also show up with their failure property as true.

If the issue is a temporary one (eg. password change, server is back online, folder is restored) you can reset this the WebHook by doing a POST request on it with the active parameter set to 1.