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.
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.
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: email@example.com Password: ...
$ git clone https://github.com/facebook/ThreatExchange.git $ cd ThreatExchange
You now have a functioning git repo that contains the sample Heroku application.
$ 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
$ git push webhooks
The application is now deployed and ready to receive information from ThreatExchange.
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"
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.