Configuring Webhooks

Permissions

Webhooks can be set up and configured by users with developer permissions on a per-deal basis. Users can see which the deals for which they have developer permissions on their Dashboard.

Please contact the DealMaker team to set up developer permissions for each of your deals.

Configuring Webhooks

At any time after signing as a user with developer permissions, head to the Profile page.

Once on the profile page, navigate to the Integrations tab. Here, you can configure DealMaker to send webhooks to a URL on your server. Below, we'll discuss the available controls here, and how they relate to configuring your server to receive webhook payloads from DealMaker.

The webhook configuration on this page will apply to all deals on which the user is marked as a developer.

Enable Webhooks

Toggle this switch to enable the delivery of webhooks to the provided Payload URL. In the event of recurring delivery failures, webhook delivery will be automatically disabled after 6 failed attempts.

Payload URL

HTTP POST requests will be sent to this URL from DealMaker. Ensure that your server is configured to receive webhook payloads at this URL. Ensure that your server is able to receive payloads at this URL, and respond with appropriate HTTP status codes.

Any HTTP status other than 200 OK returned from your server will be considered a delivery failure.

We strongly recommend using HTTPS endpoints on your server to avoid the security vulnerabilities associated with unencrypted web traffic. 

Secret

Setting a webhook secret allows you to ensure that POST requests sent to the payload URL are from DealMaker. When you set a secret, you'll receive the X-DealMaker-Signature header in the webhook POST request. You can generate a new secret, clear the secret, and copy the secret to your clipboard.

You can set up an environment variable for your server containing the secret, which you can use to verify the webhook payload in your server-side code:

See verifying payloads from DealMaker for more details on request verification using the secret. 

Leaving the Secret field blank will result in the X-DealMaker-Signature header not being included with webhook payloads sent to your server. We strongly recommend against leaving this field blank as other methods of verifying payload authenticity are considerably less reliable.

Alerts Email

This email will be used to deliver error notifications in case of a delivery failure. The field is populated with the signed in user's email by default, but any valid email address can be used.

Saving your Configuration

Once you are satisfied with your webhook configuration, click Save Changes to ensure it is applied. You can return to Profile > Integrations to change this configuration, or disable webhooks altogether, at any time.

 

Verifying payloads from DealMaker

Once your server is configured to receive payloads, it will listen for any payload sent to the endpoint you configured. An example configuration is included below in Ruby:

For security reasons, you should limit requests to this endpoint to those coming from DealMaker. DealMaker provides the facility of a secret used to validate the information. This can be accomplished by writing a simple verification method and using it to return an HTTP error code when the secret is incorrect:

How it works

When your secret token is set, DealMaker uses it to create a hash signature with each payload.

This hash signature is passed along with each request in the headers as X-DealMaker-Signature. The goal for your server is to compute a hash using your secret token (which we saved earlier as an environment variable called SECRET_TOKEN), and ensure that the hash from DealMaker matches. DealMaker uses an HMAC hexdigest to compute the hash, so our example above implements the same method to verify the hash.

Obviously, your language and server implementations may differ than this code, but the fundamentals of verifying the signature are consistent across most languages and frameworks.

No matter which implementation you use, the hash signature starts with sha1=, using the key of your secret token and your payload body

Using a plain == operator is not advised. A method like secure_compare performs a "constant time" string comparison, which renders it safe from certain timing attacks against regular equality operators.