Webhooks

Introduction

Welcome to our Webhooks documentation page. This guide will walk you through the process of registering a webhook for various events in our application. Webhooks allow your application to receive real-time notifications about specific activities. You can use these notifications to trigger actions in your system, ensuring seamless integration and automation.

Available Events

We offer a variety of webhook events that you can subscribe to, ensuring you have the flexibility to monitor the activities that are most relevant to your operations. Some events are exclusive to our Merchant and Manufacturer plans.

Standard Events

Here are some examples of the events you can subscribe to: Estimate Accepted, Lead Created, Lead Updated, etc.

You can find the complete list of available events within the application during the webhook registration or update process.

Plan Exclusive Events

Some of the events are plan exclusive and are only available for the Merchant and Manufacturer plans.

How to Register a Webhook

Step 1: Access the Webhooks Management Page

Log in to your account and navigate to the Webhooks management page found under the "My Business" > "API" section in the Buildxact Web Application.

Step 2: Create a New Webhook

  1. Click on "Add Webhook": Start by clicking the "Add Webhook" button.

  2. Enter the Webhook URL: Provide the URL where you want to receive the webhook payloads.

  3. Select State: Change the toggle to Activate\Deactivate the Webhook

  4. Select Events: Choose the events you wish to subscribe to.

  5. Store the Signing secret key (Important!) - Allows you to verify the webhook content

    1. Once you save and close the form, the secret will no longer be visible

  6. Test Webhook: You can send a test payload of a given event to the Webhook Url you provided

  7. Save the Webhook: Click "Save" to register your webhook.

Step 3: Handle Webhook Payloads

Each webhook request will contain a JSON payload with details about the event. Ensure your server is set up to parse these payloads and trigger appropriate actions in your system.

Example Payload

Here’s an example payload for an "Estimate Accepted" event:

If you need additional details for the object referenced in the payload of the Webhook, please use our Public Api to get additional data.

Step 4: Review Webhook Logs

Each webhook call is meticulously logged in our system and can be accessed by users under the "Event Log" sub-menu. This comprehensive log displays the most recent event activities and allows filtering by specific events and webhooks, accommodating those with multiple webhooks assigned to various events.

Additional Webhook Information

Hierarchy Feature: Parent and Child Tenant Webhooks

Our new Hierarchy feature allows you to register a webhook on a Parent tenant and choose whether to receive events from its Child tenants (if any). This flexibility enables more comprehensive monitoring and control over tenant-specific activities. This is only available if your tenant belongs to a hierarchy.

How It Works

  1. Registering a Webhook on a Parent Tenant:

    • When you register a webhook on a Parent tenant, you have the option to configure it to receive events from its Child tenants. On by default.

  2. Opting In or Out of Child Tenant Events:

    • During the webhook registration process, you can specify whether you want the webhook to also receive events from Child tenants. This is managed through a simple toggle in the webhook configuration interface. Also available on the Update form.

This feature ensures that you have the flexibility to streamline your webhook event handling, either centralizing event management at the Parent level or isolating events to specific tenants as required.

Retry Mechanism

To ensure reliable delivery of webhook events, we have implemented a retry mechanism. If a webhook delivery fails, we will attempt to redeliver the webhook up to three times according to the following schedule:

  1. First Retry: 5 minutes after the initial attempt.

  2. Second Retry: 30 minutes after the first retry.

  3. Final Retry: 4 hours after the second retry.

If all three attempts fail, an email notification will be sent to the user detailing the failure (see the failure notification information below).

Failure Notification

When a webhook fails all retry attempts, you will receive an email containing the following information:

  • Endpoint: The URL to which the webhook was attempting to be delivered.

  • Timestamp: The time at which each delivery attempt was made.

  • Response Content: The response body returned by your server, if any.

  • Status Code: The HTTP status code returned by your server.

This notification aims to provide you with sufficient information to diagnose and resolve the issue.

Webhook Changes

Should a webhook get disabled or its Url changed while a message is scheduled in the queue for a retry, the following will happen:

  1. If the Url is changed, the scheduled message is going to be sent to the new url.

  2. If the webhook is disabled, the message will be discarded and not retried (see more in the "Handling Disabled Webhooks" section below).

Failure Rate Monitoring

To maintain the integrity of our webhook delivery system, we monitor the failure rate of each webhook. If a webhook has a failure rate of 95% or higher within the last 12 hours or since its re-activation, the webhook will be disabled automatically. Upon disabling a webhook, an email notification will be sent to the user.

  • High Failure Rate Notification: This email will inform you that the webhook has been disabled due to a high failure rate. It will also include some details about the webhook so that you can easily identify which webhook needs troubleshooting.

During the period when a webhook is disabled, any events that occur will not be sent, and those events will be permanently missed.

Handling Disabled Webhooks

If a webhook is disabled during the processing of an event, any pending retries for that event will be dropped. This ensures that no further delivery attempts are made for events associated with disabled webhooks.

Webhook Signing Secret Key

To ensure that your server only processes webhook deliveries that were sent by Buildxact and to ensure that the delivery was not tampered with, you should validate the webhook signature before processing the delivery further. This will help you avoid spending server time to process deliveries that are not from Buildxact and will help avoid man-in-the-middle attacks. In short, this allows you to validate incoming webhook payloads against the secret, to verify that they are coming from Buildxact and were not tampered with.

How It Works

  1. Serialize the Request Body: The payload (webhook event data) is serialized into a JSON string using camelCase property naming policy.

  2. Generate the Secret Bytes: The secret key you saved (during the webhook creation) is converted into a byte array using UTF-8 encoding.

  3. Create the Hasher: An HMACSHA256 hasher is created using the secret bytes.

  4. Hash the Data: The serialized JSON payload is converted into a byte array and then hashed using the HMACSHA256 hasher.

  5. Generate the Signature: The resulting hash is converted into a Base64 string, which serves as the signature.

Here is a C# example of this process:

Validating the Payload

To validate the incoming webhook payload, perform the following steps on your server:

  1. Recompute the Signature: Use the same process described above to compute the signature for the received payload.

  2. Compare Signatures: Compare the computed signature with the signature sent in the webhook request header. If they match, the payload is valid and untampered.

This validation step is crucial for ensuring the authenticity and security of the webhook data your application receives from Buildxact. By following these steps, you can be confident that the data has not been altered in transit and originates from a trusted source.

Webhooks Summary

  • Retries: Three attempts (5 minutes, 30 minutes, 4 hours).

  • Logs: Access detailed logs for debugging and monitoring webhook events.

  • Failure Notification: Email notification sent with endpoint, timestamp, response content, and status code after all retries fail.

  • High Failure Rate: Webhook disabled and Email notification sent if 95% failure rate within 12 hours and\or since re-activation.

  • Missed Events: Events missed during the webhook disabled period.

  • Dropped Messages: Retries for disabled webhooks will be dropped.

  • Secret: Validate that the incoming webhook payloads were not tampered with and are truly coming from Buildxact.

  • Hierarchy Feature: Register webhooks on Parent tenants with the option to include or exclude events from Child tenants, allowing for flexible event management across tenant hierarchies.