Webhooks

Setting up webhooks allows Madronus to notify an external service that an event has occured.

Note: we do not send the full data of assessments etc along with webhooks. If you need to get data from objects please use the identifiers in the webhook payload, along with our APIs.

Setup

As an admin you can access webhook setup by going to Account / Webhooks.

Options

Setting up a webhook is as simple as choosing an event, and providing a URL.

alt text

• Event: Choose the even that will run this webhook. Some events will run at the same time, for example assessment_updated and assessment_status_changed.

• URL: The full URL to call the webhook. Currently all calls are done using POST.

• Security Type: Choose what kind of authentication / signature you want to use.

  • None: None ...
  • Plain Text: Sets the header Authorization to Bearer <SECRET>
  • HMAC-SHA1: Sets the header X-Webhook-Signature to sha1=<SIGNATURE>
  • HMAC-SHA256: Sets the header X-Webhook-Signature to sha256=<SIGNATURE>

• Secret: If security is set this is the secret that is used.

Security Signatures

Signatures are generated using the content of the body, along with the secret you supply.

Headers

Headers will be sent along with the webhook. All calls will contain the following headers:

• Content-Type: application/json: Content type.
• User-Agent: Madronus-Webhook/1.0: User agent being used for our webhooks.
• X-Webhook-ID': ozqtz_qi_STH2TsjshU6o: ID of the webhook configuration.
• X-Delivery-ID': POq8gCpnSqHN9sl2upL5q: ID of the specific webhook run.
• X-Event-Type': assessment_status_changed: The event type. Is duplicated in the body.
• X-Timestamp': 1755648812981: The time the event occured. Milliseconds since the epoch.

Depending on the security chosen:

• Authorization: Bearer MY_SECRET: If using plain text
• X-Webhook-Signature: sha1=0b39f8440500ed6321...: If using SHA-1
• X-Webhook-Signature: sha256=b45a31f1ffd31c1b...: If using SHA-256

Body

The body is the main payload of the webhook. It will always be a JSON string with an event and data property. The data property will depend on the event type.

Example

{
  "event": "assessment_scheduled",
  "data": {
    "assessmentId": 9692,
    "jobDateTime": "2025-08-11 23:00:00",
    "jobDateTimeTimeZone": "America/Los_Angeles",
    "jobTypeId": 84
  }
}

Events

List of Webhook Events

Response to webhooks

Webhook endpoints must respond with a 2xx HTTP code ie 200 OK. If not it is treated as a failed call.

Retries

Webhooks will retry up to 3 times (for a total of 4 calls) before failing. Retries use exponential delay from 15 seconds ie 15s, 30s then 60s.