Skip to main content

Webhooks

Webhooks are HTTP callbacks that allow different systems to communicate with each other in real-time. They're like automated messengers that deliver information when something happens, rather than requiring you to ask for it.

In the context of MaintainX®, webhooks are a way for our system to automatically notify your application when specific events occur in your account. Instead of your application polling the MaintainX API for updates, webhooks allow you to receive real-time notifications about important events like:

  • Work order status changes
  • New work orders being created
  • Asset updates

When an event occurs, MaintainX sends an HTTP POST request to the endpoint you specify. The request contains details about the event. It allows your application to react immediately to changes in MaintainX.

Set Up Webhooks​

You can configure webhooks in the following ways in the MaintainX web application or using the REST API.

When you create a webhook, you'll receive a secret that you should store securely. This secret is essential for signature verification (see Webhook Timestamps and Signatures) and can also be accessed later through the MaintainX interface if needed.

From the MaintainX Web Application​

For a quick setup, you can configure webhooks in the MaintainX web application:

  1. From the sidebar, select Settings > Integrations.
  2. On the Integrations page, select Webhooks.
  3. Select + New Webhook.
  4. Configure a webhook endpoint and choose the events you want to receive.
  5. Save the configuration.

Via the REST API​

You can configure webhooks using the REST API if you want to integrate with MaintainX in a programmatic way. The API allows you to:

  • Create new webhook subscriptions.
  • Update webhook configurations.
  • Delete webhook subscriptions.
  • Retrieve webhook secrets.

For more information about webhook API endpoints, see Subscriptions and Webhooks in the API Reference.

Webhook Timeout and Deletion​

Webhooks that don't get a successful response from your application over long periods of time might be deleted. A webhook call times out after 10 seconds. When a webhook is deleted, we send an email to the address linked to the user account that made the request.

Webhook Timestamps and Signatures​

To verify that webhook requests come from MaintainX and haven't been tampered with, we include security signatures in each webhook request. This section explains how to verify these signatures.

All webhook HTTP requests sent by MaintainX include two headers containing a timestamp and an HMAC signature that must be validated by your application:

  • x-maintainx-webhook-body-signature
  • x-maintainx-webhook-uri-signature

The timestamp is prefixed by t=. Each signature is prefixed by a scheme version. Scheme versions start with v, followed by an integer. The only valid live signature version is v1.

x-maintainx-webhook-body-signature: t=<timestamp>,v1=<signature>

Verify a Webhook Signature​

MaintainX generates signatures using a hash-based message authentication code (HMAC) with SHA-256. Here are the steps to verify a webhook signature:

  1. Extract the Timestamp and Signatures from the Header
  2. Prepare the Signed Payload String
  3. Determine the Expected Signature
  4. Compare the Signatures

Extract the Timestamp and Signatures from the Header​

  1. Split the header, using the , character as the separator, to get a list of elements.
  2. Split each element, using the = character as the separator, to get a prefix and value pair. The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature. You can discard all other elements.

Prepare the Signed Payload String​

Concatenate the following:

  • The timestamp (as a string)
  • The character .
  • The actual JSON payload (that is, the request body, or the full URI)
<timestamp>.<stringified payload>

Determine the Expected Signature​

  1. Retrieve the secret for your endpoint. Visit https://app.getmaintainx.com/settings/integrations, find the endpoint you want, and select Copy secret.
  2. Compute an HMAC with the SHA256 hash function.
  3. Use the endpoint's signing secret as the key.
  4. Use the signed_payload string as the message.
crypto.createHmac("sha256", secret).update('<timestamp>.<stringified payload>', "utf8").digest("hex")

Compare the Signatures​

  1. Compare the signature in the header to the expected signature.
  2. For an equality match, compute the difference between the current timestamp and the received timestamp.
  3. Decide whether the difference is within your tolerance. We recommend a tolerance of 5 minutes to allow for clock drift and processing delays. Webhooks with timestamps older than your tolerance window should be rejected to prevent replay attacks.

Best Practices​

  • Always verify webhook signatures to ensure requests are genuine (see Verify a Webhook Signature).
  • Return a 2xx status code as quickly as possible to acknowledge receipt (webhooks time out after 10 seconds).
  • Process webhook events asynchronously after acknowledging receipt.
  • Implement proper error handling for failed webhook deliveries.
  • Implement retry logic in your application to handle temporary failures.
  • Implement idempotency in your webhook handler to prevent duplicate processing of the same event.
  • Set up monitoring for your webhook endpoint to detect failures.
  • Consider using a webhook testing tool during development to simulate events.

Limitations​

  • Webhook URLs are currently limited to a maximum of 512 characters.