Configuring Webhooks For Subscription API

• Setup steps for your webserver
• Creating a subscription with a secure webhook
• What happens after Webhook setup is successful?
• Verify the Authenticity of demandbase call to the Webhook

1. Ensure that the server which will receive callbacks should be hosted at the callback URL provided by you in the create subscription request.
2. Webhook should support both HEAD and POST request types.
3. To validate your webhook's authenticity, Demandbase sends a HEAD request with a validation code as a request header X-DemandbaseAPI-ValidationCode. Your server should respond to the HEAD request by echoing the value received in the request header X-DemandbaseAPI-ValidationCode as a response header with the same name.

protected void doHead(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
    System.out.println(req.getHeader("X-DemandbaseAPI-ValidationCode")); // This request header is sent by Demandbase as a HEAD request to the URL configured as the webhook
    resp.setHeader("X-DemandbaseAPI-ValidationCode", req.getHeader("X-DemandbaseAPI-ValidationCode")); // Echo the header sent by Demandbase
}

Note: There might be a delay (a maximum of 2-3 minutes) before Demandbase sends the validation request to your callback webserver.

To create a subscription, see Create a New Subscription. If your webserver is ready to respond to validation requests, your request to create a subscription should be successful with the status of webhook as VERIFICATION_PENDING.

After submitting a create subscription request, the initial response will be as follows:

{
  ...,
  "webhook": {
    "url": "",
    "status": "VERIFICATION_PENDING"
  },
  ...,
  "subscriptionType": "company"
}

If Demandbase successfully completes validation of the webhook, en fetch the subscription, (see [GET] - Subscription Details). The response will be as follows:

{
  ...,
  "webhook": {
    "url": "",
    "status": "ACTIVE"
  },
  ...,
  "subscriptionType": "company"
}

If your webserver is not set up correctly to respond to the verification request from Demandbase, your subscription creation will still be successful but with webhook status DISABLED.

If webhook validation fails then fetch the subscription, see Retrieve Subscription Details. The response will be as follows:

{
  ...,
  "webhook": {
    "url": "",
    "status": "DISABLED",
    "disableReasonMessage": "Unable to reach the webhook URL",
    "signingSecret": ""
  }
  ...,
  "subscriptionType": "company"
}

The response above implies that head request failed as we were unable to reach webhook URL

• Unable to reach the webhook URL
• Required header is missing in the webhook response
• Invalid number of headers in the webhook response
• Invalid header value in the webhook response
• Incorrect header in the webhook response
• Invalid webhook URL

Demandbase generates Alerts for any change in the subscribed entities for all the Subscriptions. If any of the subscriptions have a validated webhook associated with it, then Demandbase sends a POST request to the webhook.

This POST call contains the following information in the payload:

Example:

{
  "alertId": "364559",
  "subscriptionId": "oshbv7671moesavtb0e0",
  "date": "2020-02-26 11:52:29:00+0000",
  "type": "company"
}

In order to fetch the alert details, use the Retrieve a Specific Subscription Alert call.

At the time of Subscription Creation or Subscription Updation, you can use the signingSecret parameter to establish a secret key between your webhook and Demandbase. This key is used by Demandbase to create a header X-DemandbaseAPI-AlertDataSignature. The content of this header is the same as the payload encrypted by signingSecret via HMAC SHA1 algorithm. You can decrypt this header using the same signingSecret and verify that the payload is the same as the decrypted header content. This establishes the authenticity of the POST call.

The X-DemandbaseAPI-AlertDataSignature header is sent IF AND ONLY IF the webhook is configured with a signing secret.