Webhooks for ThreatExchange

ThreatExchange support for Webhooks is an experimental feature. We look forward to developing the feature further based on feedback from the ThreatExchange community.

ThreatExchange Webhooks allow you to receive information in realtime for ThreatIndicators, ThreatDescriptors, ThreatTags, MalwareAnalyses, and MalwareFamilies. By receiving push notifications on any new data, this replaces the need to periodically pull data manually.

Follow the steps below to get Webhooks setup for your ThreatExchange app.

1. Create a URL Callback Endpoint

2. Enable Webhooks in your App

3. Verify Integration in Your Logs

1. Create a URL Callback Endpoint

You'll need to prepare an endpoint that will act as your callback URL by setting up an external server. This URL will need to be accessible by Facebook servers, be able to receive both the POST data that is sent when an update happens, and also accept GET requests in order to verify subscriptions.

To make it easy, we've written sample code that you can deploy immediately in order to receive updates (you will still need to write code to process these according to your app logic, though). If you do not want to use this code and want to set this up yourself from scratch, follow the webhooks documentation found here.

The following guide will work through setting up a Heroku server with the sample code available in the ThreatExchange Github repo.

  • First, setup a Heroku account and download the Heroku Command Line Interface. You'll also need to install PHP, Composer, and Git if you haven't already.

  • Within your local command shell or terminal, login using the email address and password you used when creating your Heroku account.

$ heroku login 
Enter your Heroku credentials. 
Email: te@example.com
  • Next, clone the Webhooks code by executing the following commands
$ git clone https://github.com/facebook/ThreatExchange.git
$ cd ThreatExchange

You now have a functioning git repo that contains the sample Heroku application.

  • Next, create and deploy the Heroku app to receive your callback URL.
$ heroku create
Creating sharp-rain-871... done, stack is cedar-14
http://sharp-rain-871.herokuapp.com/ | https://git.heroku.com/sharp-rain-871.git
Git remote heroku added

Heroku generates a random app name which is closely related to your callback URL. In this case, it's http://sharp-rain-871.herokuapp.com/

  • Now, deploy the Webhooks code.
$ git push webhooks

The application is now deployed and ready to receive information from ThreatExchange.

2. Enable Webhooks in your App

Now that you have set up a server and a valid callback URL, enable Webhooks in your Developer's App.

Visit the Facebook Apps Dashboard and select the ThreatExchange-provisioned application.

In the right-hand side bar, click on "Add Product" then click "Webhooks"

Next, click "New Subscriptions" and select "ThreatExchange"

  • Here, you'll add in your callback URL. If you use the sample code provided in the Threatexchange repo, make sure to ammend to the Heroku URL the following path: /get_updates.php
  • For the verify token, choose any non-empty string. When you add a new subscription, or modify an existing one, Facebook servers will make a GET request to your callback URL in order to verify the validity of the callback server.

3. Verify Integration in Your Logs

Congratulations, you've set up Webhooks for ThreatExchange! Your server should now be receiving POSTS from Facebook. The returned fields will map back to the standard fields for ThreatIndicators, ThreatDescriptors, ThreatTags, MalwareAnalyses, and MalwareFamilies.

If you've setup a Heroku server with our code sample referenced above, you can view the incoming threats in your logs with the following command.

$ heroku logs --tail 

Note: If your server is behind a firewall, you may need to add Facebook server IPs to your allow list to ensure we can send updates to your callback URLs. To get the current list of Facebook Server IP addresses, view the documentation here.