Receiving Webhookslink

Webhooks are delivered to the defined target URL, using the HTTP verb set as method (either POST or PUT).

Endpoint Requirementslink

Your webhook endpoint must:

HTTP Headerslink

Webhooks include these headers:

Webhook Payloadlink

The payload contains the affected resource object in JSON format inside the data key, in a very similar way and structure as if requested via GET method, so there is no need to execute additional requests unless you need some relationship data. See the example below:

{
  "data": {
    "type": "failure",
    "id": "12345",
    "attributes": {
      "failure_id": 12345,
      "description": "HVAC not cooling",
      "state": "WAITING_APPROVAL",
      "priority": 2,
      "local_id": 6789,
      (...)
    }
  }
}

Responding Immediatelylink

To acknowledge receipt of the webhook, your endpoint must return a 2xx HTTP status code as quickly as possible once received. All response codes outside this range, including 3xx codes, indicate that you did not receive the webhook.

If you process the webhook before responding (e.g. transforming the data, loading it to database or sending it to other services), this may cause the request to timeout, making our servers assume the webhook as not delivered, and webhooks marked as not delivered will be retried. In such cases, be prepared to handle duplicated events by checking the X-Request-Uuid HTTP request header. Our target timeout limit for webhooks is 30 seconds.

A common strategy to handle webhooks is to store the request payload on a message queue, respond with a 200 OK, and use a background worker to process the messages in the queue.

Not Delivered Webhookslink

If your endpoint does not respond with a 2xx HTTP status code for any reason, Infraspeak will automatically retry the delivery of that webhook with exponential backoff for up to 12 retries. Note that retries for a particular webhook always goes with same value for the X-Request-Uuid HTTP request header, which you can use to prevent duplicate events.

If for some reason your endpoint is still unable to respond successfully during that period, the webhook will be considered failed, and we will no longer retry sending it.

Webhooks are disabled automatically to ensure system reliability in the following cases:

• Slow receivers: the webhook experiences a timeout when attempting to connect to the webhook receiver or reaches the timeout limit while waiting for a response.
• Unstable receivers: the webhook receiver returns a response code other than 2xx range (3xx, 4xx or 5xx).
• Incorrectly configured receivers: the webhook encounters invalid HTTP responses.

All admin users within your Infraspeak entity will receive notifications when a webhook is automatically disabled. Disabled webhooks can be manually re-enabled.

Delivery Loglink

Every webhook sent has a delivery log. You can access it via web interface on Settings → Integrations → Webhook logs. There, you will find a list with all webhooks sent, where each row has:

• The event that triggered the webhook.
• The target endpoint URL.
• The response HTTP status code received from the endpoint.
• The delivery date and time.

By clicking on a row, you can check additionally:

• The HTTP request headers.
• The request body.
• The response body received from the endpoint.

Best Practiceslink

• Respond quickly: return 2xx within 30 seconds. For heavy processing, process asynchronously. A common strategy is to store the request payload on a message queue, respond with a 200 OK, and use a background worker to process the messages in the queue.
• Monitor webhook health to avoid webhook auto-deactivation.
• Use the request header X-Request-Uuid to handle duplicate deliveries (idempotency).
• Handle Out-of-Order delivery since events may arrive out of order. A common strategy is to compare the payload's update date (e.g.: updated_at, date_updated) with your existing's update date: if you have a newer state, ignore the older event.
• Handle errors gracefully without breaking the webhook flow (return 2xx to prevent retries).