MaintainX Subscriptions & Webhooks API
Webhooks in MaintainX What are 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 repeatedly checking our API for updates (a process known as "polling"), webhooks allow you to receive real-time notifications about important events like: Work order status changes New work orders being created Asset updates And more... 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 the following ways: From the MaintainX Web Application For a quick setup, you can configure webhooks in the MaintainX web application: From the sidebar, select Settings > Integrations. Then, on the Integrations page, select Webhooks Click + New Webhook Configure a webhook endpoint and select the events you want to receive Save the configuration Via the REST API You can configure webhooks using our 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. ⚠️ Warning Webhooks that don't get a successful response from your application over long periods of time might be deleted. A webhook call will timeout after 10 seconds. When a webhook is deleted, we send an email to the address linked to the user account that made the request. Security and Verification 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. Verify Webhook 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 ℹ️ Note When creating a webhook, you'll receive a secret that should be securely stored on your end. This secret is essential for signature verification and can also be accessed later through the MaintainX interface if needed. 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> Signature Verification Process MaintainX generates signatures using a hash-based message authentication code (HMAC) with SHA-256. Here are the steps to verify a webhook signature: Extract the timestamp and signatures from the header Split the header, using the , character as the separator, to get a list of elements. 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. To 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 Retrieve the secret for your endpoint. Visit [https://app.getmaintainx.com/settings/integrations](https://app.getmaintainx.com/settings/integrations), find the endpoint you want, and select Copy secret. Compute an HMAC with the SHA256 hash function. Use the endpoint's signing secret as the key. Use the signed_payload string as the message. crypto.createHmac("sha256", secret).update('<timestamp>.<stringified payload>', "utf8").digest("hex") Compare the signatures Compare the signature in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp. 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 Security and Verification section above). Return a 2xx status code as quickly as possible to acknowledge receipt (our webhooks will timeout 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 Need Help? If you need help implementing webhooks or troubleshooting, contact our Support team from the MaintainX web application. From the sidebar, select Support, then select Contact Support.