Integrating with DealMaker
      Back to home
      1. Knowledge Center
      2. Step 1: Getting Set up on DealMaker
      3. Integrating with DealMaker

      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

      To configure your webhooks, click on the dropdown menu in the top right corner and select "Integrations".

      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.

       

       

      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 Payload Verification with 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.

      Add Deals

      Search and select deals to add them to the endpoint you are setting up. You may select from any of the deals on which you are a team member. Because you may create any number of endpoints, you may choose to direct different deals to different endpoints, in whichever combination suits your usage. Here you may remove deals from the endpoint as well.

      Saving your Configuration

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

      Multiple Endpoints

      It is now possible to set up multiple endpoints. This means you may divert different deals to different destinations, or direct all deals to one endpoint, or any combination thereof. 

      Edit Endpoint

      You may edit your endpoints at any time by clicking "edit endpoint" and editing the fields, then clicking "Save Changes to Endpoint"

       

      Payload Verification with DealMaker

      For enhanced security, your server's endpoint should only accept requests that originate from DealMaker. DealMaker sends a unique hash signature with every payload to ensure the request's authenticity. This signature is found in the X-DealMaker-Signature header.The signature is created by using the SHA1 algorithm to calculate an HMAC hex digest of the payload's body, with the secret token you defined serving as the key. The final header value is formed by prepending the resulting hash with the string sha1=.
      To verify the payload on your end, you must:
      1. Access the raw body of the incoming request.
      2. Retrieve the X-DealMaker-Signature from the request header.
      3. Calculate your own HMAC hex digest using SHA1 with your secret token and the raw payload body.
      4. Prepend the string sha1= to your calculated hash value.
      5. Compare your prefixed, calculated hash with the signature received in the header.
      It is critical that you use a secure comparison method (e.g., hash_equals in PHP, secure_compare in Ruby) to prevent timing attacks. If the hashes match, you can be confident the request is from DealMaker and process the data. If they don't, your server should return an HTTP error code.

      Consistency Across Languages

      While specific code implementations might differ, the basic approach to verifying signatures remains largely consistent across various programming languages and frameworks.

      Example Header

      The X-DealMaker-Signature header will contain a value that is a combination of the sha1= prefix and the calculated hash. The following is an example of how the complete header would appear:
      X-DealMaker-Signature: sha1=f95709971933b91a27e7d32c589a17409f582312
      In this example, f95709971933b91a27e7d32c589a17409f582312 is the 40-character SHA1 HMAC hex digest of the payload body. Your verification logic should calculate the same hash and then add the sha1= prefix before performing the comparison.

      Documentation

      Please refer to our Developer Documentation for the latest guidelines on using Webhooks. You'll find detailed instructions on how to seamlessly integrate them with your portal and other platforms!