Agent webhooks

Agent webhooks send an Agent result to your system when an alert condition is met.

Webhooks are optional. Configure one only when your system needs to receive Agent alerts automatically. If you only want to review results in the dashboard, no webhook is required.

🛠️
Follow the Verify Agent webhooks recipe to build a complete endpoint in Python, Node.js or PHP, or check a single webhook with curl and openssl, that validates signatures, echoes the verification challenge, and receives Agent notifications.

How Agent webhooks work

Create a public HTTPS endpoint in your system.
Add its URL to the Agent's Webhook URL field.
Trustfull sends a verification request to the endpoint.
Your endpoint echoes the verification challenge.
Trustfull saves the URL after successful verification.
When the Agent meets its alert condition, Trustfull sends the complete result to the endpoint.
Your endpoint verifies the signature and acknowledges the notification.

Requirements

Your webhook endpoint must:

Use HTTPS.
Resolve to a public host.
Accept JSON POST requests.
Not redirect verification requests.
Return verification responses within five seconds.
Return notification responses within ten seconds.

Private IP addresses, localhost addresses, and hosts that do not resolve publicly are not accepted.

Respond to the verification request

When you add or change a webhook URL, Trustfull sends a request like this:

{
  "type": "verification",
  "challenge": "a-random-value"
}

Return 200 OK and echo the exact challenge in a JSON response:

{
  "challenge": "a-random-value"
}

Trustfull does not save the webhook URL if the endpoint times out, redirects, returns another status, or returns a different challenge.

Receive an Agent notification

When an alert condition is met, Trustfull sends the complete result as a JSON POST to the verified URL.

Return any 2xx status within ten seconds to acknowledge the notification. A timeout or non-2xx response is treated as a failed delivery and may be retried.

Your handler should be idempotent so receiving the same notification again does not repeat a business action.

Verify webhook signatures

Trustfull signs both verification requests and Agent notifications. Validate the signature before parsing or acting on the payload.

Each request includes these headers:

Header	Description
`x-trustfull-signature`	Base64-encoded RSA signature.
`x-trustfull-key-id`	ID of the public key used to sign the request.
`x-trustfull-timestamp`	Unix timestamp used in the signature.

1. Retrieve the public keys

Send an authenticated request to:

GET https://api.fido.id/1.0/webhook/keys
x-api-key: [your_app_key]

Select the public key whose ID matches x-trustfull-key-id.

2. Build the signed value

Join the timestamp, a full stop, and the exact raw request body:

<x-trustfull-timestamp>.<raw-request-body>

Do not parse, reformat, or re-encode the body before verification.

3. Verify the signature

Decode x-trustfull-signature from Base64 and verify it with the selected public key using RSA PKCS#1 v1.5 and SHA-256.

Reject the request if verification fails. You should also reject timestamps outside a short tolerance window to reduce replay risk.

Troubleshooting

Problem	What to check
The URL is rejected	Confirm that it uses HTTPS and resolves to a public address.
Verification times out	Return the response within five seconds.
The challenge is rejected	Echo the exact value received in `challenge`.
Notifications are retried	Return a `2xx` status within ten seconds.
Signature verification fails	Use the raw body and the key identified by `x-trustfull-key-id`.

Return to Agents for scheduling, alerts, and Agent lifecycle information.