​
Introduction

Webhooks provide a way for Buildr API to notify your application or service about events that occur in the Buildr platform, such as a new opportunity being created or updated. With webhooks, your application can stay in sync with Buildr API without needing to constantly poll the API for updates.

​
Creating a webhook

You can create webhooks two different ways: in the “Developer” tab of your Account Settings, or by using the API. To create a webhook with the API, you’ll need to send a POST request to the /api/2023-01/webhooks endpoint with a JSON payload that specifies the webhook configuration. Here’s an example of a request body: 
{
  "webhook": {
    "url": "https://example.com/webhook",
    "description": "Webhook for example.com",
    "filter_types": [
      "opportunity.create"
    ],
    "secret": "secret",
    "rate_limit": 100
  }
}
The url field specifies the URL of your application or service that will receive webhook notifications. The description field is an optional string that describes the webhook. The filter_types field is an array of event types that the webhook will be subscribed to. In this example, the webhook will only be notified about opportunity created events. The secret field is an optional secret key that can be used to sign and verify webhook payloads. If provided, Buildr API will include a signature in the webhook payload that can be used to verify the authenticity of the payload. The rate_limit field is an optional integer that specifies the maximum number of webhooks that can be sent to the endpoint per minute. If not specified, the default rate limit is 60 webhooks per minute. Detailed API documentation for creating webhooks can be found here

​
Example Payload

Here’s an example of a payload that your application might receive for an opportunity created event: 
{
  "id": 2279,
  "url": "https://example.com/opportunities/2279"
}
The payload contains the id of the new opportunity and its url on the Buildr platform.

​
Supported Webhooks

There are six total webhooks that can be subscribed to. They are:
  • contact.create
  • contact.update
  • opportunity.create
  • opportunity.update
  • company.create
  • company.update

​
Securing your webhook

To secure your webhook, you should use the secret field to sign and verify webhook payloads. When you receive a webhook payload, you can verify its authenticity by calculating a signature using the same secret key that you provided in the webhook configuration, and comparing it to the signature included in the payload. Here’s an example of how to verify a webhook payload in Node.js (Express): 
import { Webhook } from "svix";
import bodyParser from "body-parser";

const secret = "your-webhook-secret";

app.post("/webhook", bodyParser.raw({type: "application/json"}), (req, res) => {
  const payload = req.body;
  const headers = req.headers;

  const wh = new Webhook(secret);
  let msg;
  try {
    msg = wh.verify(payload, headers);
  } catch (err) {
    res.status(400).json({});
  }

  // Do something with the message...

  res.json({});
});

​
Conclusion

In this guide, we’ve covered how to create and secure webhooks for the Buildr API. By subscribing to webhook events, your application can stay in sync with Buildr API without needing to constantly poll the API for updates.