Securing Webhooks

Webhook APIs will secure your webhooks in two ways:

  1. Require challenge response checks to validate that the webhook owner is the Twitter app owner.
  2. A signature header in each POST request for your app to validate source.

Required Challenge Response Check

In order to verify that you are both the owner of the app and the webhook URL, Twitter will perform a Challenge Response Check (CRC), which is not to be confused with a cyclic redundancy check.

A GET request with a parameter named crc_token will be sent to your webhook URL. Your endpoint must return a JSON response with a response_token that is a base64 encoded HMAC SHA-256 hash created from the crc_token and your app Consumer Secret.

The crc_token should be expected to change for each incoming CRC request. The crc_token should be used as the message in the calculation, where your Consumer Secret is the key.

In the event that the response is invalid, events will cease to be sent to the registered webhook.

The CRC request will occur

  • When a webhook URL is registered.
  • Daily (once per 24 hours) to validate your webhook URL.

Response requirements

  • Valid response_token and JSON format.
  • Latency less than 1 second.
  • 200 HTTP response code.

Example response token generation in python

import base64
import hmac
import hashlib

sha256_hash_digest = hmac.new(APP_CONSUMER_SECRET, msg=crc_token, digestmod=hashlib.sha256).digest()

response = {
  'response_token': 'sha256=' + base64.b64encode(sha256_hash_digest)
}

Example JSON response

{
  "response_token": "sha256=x0mYd8hz2goCTfcNAaMqENy2BFgJJfJOb4PdvTffpwg="
}

Validating the Signature Header

With each incoming POST request from Twitter a hash signature will be passed in the headers as x-twitter-webhooks-signature. This signature can be used to validate source of the data. The hash signature starts with sha256= indicating the use of HMAC SHA-256 to encrypt your Twitter app Consumer Secret and payload.

Steps to validate request

  1. Create a hash using your consumer secret and incoming payload body.
  2. Compare created hash with the base64 encoded x-twitter-webhooks-signature value. Use a method like compare_digest to reduce the vulnerability to timing attacks.

Language Specific HMAC Libraries

Additional Security Guidelines

The following are additional security recommendations for your web application.

Twitter Aggregate Network Blocks

For added security you may wish to whitelist the following aggregate network blocks:

  • 199.59.148.0/22
  • 199.16.156.0/22

Recommended Server Configurations

  • A- rating on ssllabs.com test.

  • Enable TLS 1.2

  • Enable Forward Secrecy

  • Disable SSLv2

  • Disable SSLv3 (because POODLE)

  • Disable TLS 1.0

  • Disable TLS Compression

  • Disable Session Tickets unless you rotate session ticket keys.

  • Set the “ssl_prefer_server_ciphers” or “SSLHonorCipherOrder” option in the SSL Configuration “on”

  • Ensure the list of ciphers is a modern list such as:

    ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES128-SHA256:AES128-SHA:AES256-GCM-SHA384:AES256-SHA256:AES256-SHA:ECDHE-RSA-DES-CBC3-SHA:DES-CBC3-SHA