users/webhooks

Supported methods

List methods:GETPOST

Instance methods:GETDELETEPOST

Webhooks list

GET: Listing of WebHook configured for a user

GET https://api.context.io/lite/users/id/webhookstest it
idUnique id of a user accessible through your API key

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 user or not,
    "failure": booleantrue means we had issues connecting to the user and gave up after a couple retries. The failure_notif_url is called when a webhook's failure property becomes true.,
    "webhook_id": stringId of the webhook,
    "resource_url": stringComplete URL of the webhook,
    filter_*: stringValue of a filter assigned to this webhook when created,
    ...
  },
  ...
]

POST: Create a new WebHook on a user

POST https://api.context.io/lite/users/id/webhookstest it
idUnique id of a user accessible through your API key

Parameters

nametypedescription
required:
callback_urlstring
(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.
failure_notif_urlstring
(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.
optional:
filter_tostringCheck for new messages sent to a given name or email address. Also accepts a comma delimited list of email addresses.
filter_fromstringCheck for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses.
filter_ccstringCheck for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses.
filter_subjectstringCheck for new messages with a subject matching a given string or regular expression
filter_threadstringCheck for new messages in a given thread. Value must be a email_message_id of an existing message currently in the thread.
filter_file_namestringCheck for new messages where a file whose name matches the given string is attached. You can filter names using typical shell wildcards such as *, ? and [] or regular expressions by enclosing the search expression in a leading / and trailing /. For example, *.pdf would give you all PDF files while /\.jpe?g$/ would return all files whose name ends with .jpg or .jpeg
filter_folder_addedstringCheck 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_to_domainstringCheck for new messages sent to a given domain. Also accepts a comma delimited list of domains.
filter_from_domainstringCheck for new messages sent from a given domain. Also accepts a comma delimited list of domains.
include_bodyintegerSet to 1 to include message bodies in the result.
body_typestringUsed when include_body is set to get only body parts of a given MIME-type (for example text/html)
include_headermixedSet to 1 or raw to include message headers in the result.

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

GET https://api.context.io/lite/users/id/webhooks/webhook_idtest it
idUnique id of a user accessible through your API key
webhook_idUnique id of the webhook instance.

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 user or not,
  "failure": booleantrue means we had issues connecting to the user and gave up after a couple retries. The failure_notif_url is called when a webhook's failure property becomes true.,
  "webhook_id": stringId of the webhook,
  "resource_url": stringComplete URL of the webhook,
  filter_*: stringValue of a filter assigned to this webhook when created,
  ...
}

POST: Change properties of a given WebHook

POST https://api.context.io/lite/users/id/webhooks/webhook_idtest it
idUnique id of a user accessible through your API key
webhook_idUnique id of the webhook instance.

Parameters

nametypedescription
optional:
callback_urlstring
(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.
failure_notif_urlstring
(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.
activeintegerThe active property of a WebHook allows you to pause (set to 0) or resume (set to 1) it.
filter_tostringCheck for new messages sent to a given name or email address. Also accepts a comma delimited list of email addresses.
filter_fromstringCheck for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses.
filter_ccstringCheck for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses.
filter_subjectstringCheck for new messages with a subject matching a given string or regular expression
filter_threadstringCheck for new messages in a given thread. Value must be a email_message_id of an existing message currently in the thread.
filter_file_namestringCheck for new messages where a file whose name matches the given string is attached. You can filter names using typical shell wildcards such as *, ? and [] or regular expressions by enclosing the search expression in a leading / and trailing /. For example, *.pdf would give you all PDF files while /\.jpe?g$/ would return all files whose name ends with .jpg or .jpeg
filter_folder_addedstringCheck 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_to_domainstringCheck for new messages sent to a given domain. Also accepts a comma delimited list of domains.
filter_from_domainstringCheck for new messages sent from a given domain. Also accepts a comma delimited list of domains.
include_bodyintegerSet to 1 to include message bodies in the result.
body_typestringUsed when include_body is set to get only body parts of a given MIME-type (for example text/html)
include_headermixedSet to 1 or raw to include message headers in the result.

Response body

{
  "success": booleanWhether modification succeeded,
  "resource_url": string The URL of the updated webhook resource,
}

DELETE: Cancel a WebHook

DELETE https://api.context.io/lite/users/id/webhooks/webhook_idtest it
idUnique id of a user accessible through your API key
webhook_idUnique id of the webhook instance.

Response body

{
  "success": booleanWhether deletion succeeded,
}

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.

When you receive the POST request from our servers, it is important to respond to it with a 200 before doing any additional processing.

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": {
      "message_id": stringThe id id that should use to retrieve more information about the message from the lite API,
      "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),
      "references": arrayList of email_message_ids that are in the same message thread,
      "date": numberUnix timestamp of message date,
      "subject": stringSubject of the message,
      "folders": arrayList of folders (or Gmail labels) this message is found in,
    },
    "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
}
Authenticating 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 authenticate 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 authenticated
}
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]