MaintainX Subscriptions & Webhooks API

Webhooks in MaintainXWhat 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 WebhooksYou can configure webhooks the following ways:From the MaintainX Web ApplicationFor 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 configurationVia the REST APIYou 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 mightbe 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 madethe request. Security and VerificationTo 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 SignaturesAll 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 ProcessMaintainX 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 ofelements. Split each element, using the = character as the separator, to get a prefixand value pair. The value for the prefix t corresponds to the timestamp, and v1 correspondsto 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 receivedtimestamp. Decide whether the difference is within your tolerance. We recommend a tolerance of 5 minutesto 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 Verificationsection above). Return a 2xx status code as quickly as possible to acknowledge receipt (our webhooks will timeoutafter 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 charactersNeed 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.