Certificate Transparency Webhook

You can receive information in realtime for your domain's certificates by registering a Webhook and defining the domains you wish to monitor. Every time we detect a new certificate issued for these domains, we'll send a notification to your callback URL with information about the certificate. These push notifications replace the need to periodically pull data manually.

Follow the steps below to set up for your Certificate Transparency Webhook.


1. Create a URL Callback Endpoint

2. Enable Webhooks for Your Certificates

3. Using the Graph API Explorer to Interact with Your Webhook

4. Verify Integration

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.

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

  1. Set up your Facebook app in the App Dashboard and a Heroku account, if you do not already have them.
  2. Go to the Graph API Webhooks Heroku Sample, and click on the Deploy to Heroku button.
  3. Create and deploy the Heroku app to receive your callback URL.
    a. Enter a name for your app or let Heroku assign a random one. Click Deploy App.
    b. After the app is deployed, click Manage App and select the Settings tab in the dashboard.
    c. Click Reveal Config Vars, and create a TOKEN config var with whatever value you wish and a APP_SECRET config var with your Facebook app's App Secret as the value.
  4. Click Open App in the upper right corner to see your callback URL. This page can also be used to view Webhooks responses.

The application is now deployed and ready to receive information from any Webhooks you set up.

2. Enable Webhooks for Your Certificates

Now that you have set up a server and a valid callback URL, you can enable Webhooks through the App Dashboard.

  1. In the App Dashboard, go to Products > Webhooks, select Certificate Transparency from the drop-down menu, then click Subscribe to this topic.
  2. Enter the Callback URL and Verify Token (i.e., the TOKEN config var you set up in the previous section), and click Verify and Save.

See Webhooks - Setting Up Subscriptions for more information.

3. Using the Graph API Explorer to Interact with Your Webhook

Once you are subscribed to the Certificate Transparency Webhook, you can get information about your subscriptions from the Graph API Explorer.

Select your app from the Application drop-down menu in the upper right corner. Then, select Get App Token from the Get Token drop-down menu. You are now ready to access your Certificate Transparency Webhook information.

Subscriptions

You can verify you are subscribed to the Certificate Transparency Webhook by running a GET call with {your-app-id}/subscriptions. This will display information such as the callback URL and if the Webhook is active.

Subscribed Domains

You can see your subscribed domains by running a GET call with {your-app-id}/subscribed_domains?fields=domain. The domain field allows for the displaying of the actual domain names.

Subscribe to a New Domain

You can subscribe to a new domain by running a POST call with {your-app-id}/subscribed_domains with the subscribe field – click Add a field and enter subscribe for the Name and the domain you wish to monitor for the Value.

You will see a "success": true response if there were no problems.

4. Verify Integration

Congratulations, you've set up Webhooks for Certificate Transparency!

If you wish to test that everything is working properly, you can send a test notification to your callback URL.

  1. In the App Dashboard, go to Products > Webhooks > Certificate Transparency.
  2. You should see an entry for certificate. Click on the Test button for this entry.
  3. A pop-up dialog will show you a sample response. Click Send to My Server to trigger the actual notification. You should see the Webhooks response at your callback URL.

Your server will now receive POST responses that look like the following from Facebook whenever a certificate changes.

[
  {
    "entry": [
      {
        "id": "1381739901945384",
        "changed_fields": [
          "certificate"
        ],
        "time": 1510160948
      }
    ],
    "object": "certificate_transparency"
  }
]

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