Skip to main content

​
What are Mandate webhooks?

Webhooks deliver real-time event notifications to your server via HTTP POST requests. When an agent event occurs (approval needed, transaction confirmed, circuit breaker tripped), Mandate sends a JSON payload to your configured endpoint. Use webhooks to build custom dashboards, trigger automated workflows, or feed data into monitoring systems.

​
Webhook API

Manage webhooks per agent through the API:
EndpointMethodDescription
/api/agents/{agentId}/webhooksGETList configured webhooks for the agent.
/api/agents/{agentId}/webhooksPUTCreate or update webhook configuration.
/api/agents/{agentId}/webhooks/testPOSTSend a test payload to verify the endpoint.

​
Webhook types

Three webhook types are available:
TypeConfiguration
slackurl: Slack incoming webhook URL.
telegrambot_token: Telegram bot token. chat_id: target chat ID.
customurl: your endpoint URL. secret: shared secret for HMAC verification.
Configure webhook types on the Notifications page or via the PUT endpoint.

​
Payload format

Every webhook delivery sends a JSON body: 
{
  "event_type": "approval_pending",
  "agent_id": "ag_abc123",
  "intent_id": "int_xyz789",
  "status": "approval_pending",
  "metadata": {
    "action": "transfer",
    "amount_usd": "150.00",
    "to": "0xRecipientAddress",
    "reason": "Monthly subscription payment",
    "risk_level": "MEDIUM"
  },
  "timestamp": "2026-03-26T14:30:00Z"
}
The event_type field matches one of: approval_pending, intent_confirmed, intent_failed, circuit_breaker_tripped. The metadata object varies by event type but always includes the relevant transaction or agent details.

​
Secret verification

For custom webhooks, Mandate signs every payload using HMAC-SHA256 with your configured secret. The signature is included in the X-Mandate-Signature header. Verify incoming webhooks on your server:
TypeScript
import { createHmac } from 'crypto';

function verifySignature(payload: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return expected === signature;
}

// In your webhook handler:
const isValid = verifySignature(rawBody, req.headers['x-mandate-signature'], YOUR_SECRET);
Always verify the X-Mandate-Signature header before processing webhook payloads. Without verification, an attacker could send forged events to your endpoint.

​
Retry policy

If your endpoint returns a non-2xx status code or times out, Mandate retries the delivery:
AttemptDelay
1st retry~1 minute
2nd retry~5 minutes
3rd retry~30 minutes
After 3 failed attempts, the delivery is marked as failed. Check the webhook delivery log in the dashboard to see failed attempts and their response codes.

​
Testing

Use the test endpoint to verify your configuration:
curl
curl -X POST https://app.mandate.md/api/agents/{agentId}/webhooks/test \
  -H "Authorization: Bearer mndt_test_abc123" \
  -H "Content-Type: application/json"
This sends a sample payload with event_type: "test" to your configured endpoint. Verify that your server receives the request, validates the signature, and returns a 200 response.

​
Next Steps

Notifications

Configure which events trigger webhook deliveries.

API Reference

Full API documentation for all Mandate endpoints.