Webhook API Documentation

Webhook Integration

The Failsafe Radar v2 includes a lightweight webhook functionality that allows clients to register up to 5 webhooks per API key and receive intel API results asynchronously.

Key Features

Up to 5 webhooks - Register multiple endpoints for redundancy
Simple registration - Just provide a URL, no extra configuration needed
Async processing - Get immediate response, results delivered to webhooks
Retry logic - 3 retry attempts with exponential backoff
Redis persistence - Webhooks survive server restarts
Comprehensive logging - Full audit trail of webhook activities

Webhook Endpoints

1

Register a Webhook

POST/api/v2/webhooks — Register a new webhook URL to receive intel results.

cURL Example

curl -X POST "https://api.radar.getfailsafe.com/api/v2/webhooks" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-webhook-endpoint.com/intel-results"}'

Request Body

{
  "url": "https://your-webhook-endpoint.com/intel-results"
}

• url (required): HTTPS webhook endpoint URL

Response

{
  "success": true,
  "webhook": {
    "id": "wh_1640995200000_abc123def",
    "url": "https://your-webhook-endpoint.com/intel-results",
    "created": "2024-01-15T10:30:00.000Z"
  },
  "message": "Webhook registered successfully",
  "timestamp": "2024-01-15T10:30:00.000Z"
}
2

List Webhooks

GET/api/v2/webhooks — List all registered webhooks for your API key.

cURL Example

curl -X GET "https://api.radar.getfailsafe.com/api/v2/webhooks" \
  -H "x-api-key: your-api-key"

Response

{
  "success": true,
  "webhooks": [
    {
      "id": "wh_1640995200000_abc123def",
      "url": "https://your-webhook-endpoint.com/intel-results",
      "created": "2024-01-15T10:30:00.000Z",
      "deliveryCount": 42,
      "lastDelivery": "2024-01-15T12:45:00.000Z"
    }
  ],
  "count": 1,
  "timestamp": "2024-01-15T12:46:00.000Z"
}
3

Delete a Webhook

DELETE/api/v2/webhooks/:webhookId — Delete a specific webhook.

cURL Example

curl -X DELETE "https://api.radar.getfailsafe.com/api/v2/webhooks/wh_1640995200000_abc123def" \
  -H "x-api-key: your-api-key"

Response

{
  "success": true,
  "message": "Webhook deleted successfully",
  "timestamp": "2024-01-15T10:35:00.000Z"
}
4

Get Webhook Statistics

GET/api/v2/webhooks/stats — Get delivery statistics for all your webhooks.

cURL Example

curl -X GET "https://api.radar.getfailsafe.com/api/v2/webhooks/stats" \
  -H "x-api-key: your-api-key"

Response

{
  "success": true,
  "stats": {
    "total": 3,
    "totalDeliveries": 156,
    "webhooks": [
      {
        "id": "wh_1640995200000_abc123def",
        "url": "https://your-webhook-endpoint.com/intel-results",
        "deliveryCount": 42,
        "lastDelivery": "2024-01-15T12:45:00.000Z"
      }
    ]
  },
  "timestamp": "2024-01-15T12:46:00.000Z"
}

Intel API with Webhook Delivery

Synchronous Mode (Default)

cURL Example

curl -X GET "https://api.radar.getfailsafe.com/api/v2/intel?address=0x742d35Cc6634C0532925a3b8a73bf3f6" \
  -H "x-api-key: your-api-key"

Returns intel results in the same response as the synchronous mode.

Asynchronous Webhook Mode (Separate Endpoint)

cURL Example

curl -X POST "https://api.radar.getfailsafe.com/api/v2/intel/webhook" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"address": "0x742d35Cc6634C0532925a3b8a73bf3f6"}'

Request Body

{
  "address": "0x742d35Cc6634C0532925a3b8a73bf3f6"
}

• address (required): Blockchain address to analyze

Immediate Response

{
  "success": true,
  "message": "Intel analysis started - results will be delivered to registered webhooks",
  "correlation_id": "req_abc123def456",
  "timestamp": "2024-01-15T10:40:00.000Z"
}

Webhook Delivery (to your registered endpoints)

{
  "timestamp": "2024-01-15T10:40:05.000Z",
  "correlation_id": "req_abc123def456",
  "webhook_id": "wh_1640995200000_abc123def",
  "data": {
    "success": true,
    "data": {
      "address": "0x742d35Cc6634C0532925a3b8a73bf3f6",
      "entity": {
        "type": "exchange",
        "name": "Binance Hot Wallet"
      },
      "risk_assessment": {
        "risk_score": 15,
        "risk_level": "low"
      },
      "recommendation": "PROCEED",
      "classification": "Legitimate Exchange",
      "risk_tags": ["exchange", "high-volume"],
      "priority": "routine",
      "labels": ["exchange", "binance", "hot-wallet"],
      "chains_with_activity": ["ethereum", "bsc"]
    },
    "message": "Address intelligence processed successfully",
    "timestamp": "2024-01-15T10:40:05.000Z",
    "processing_time_ms": 2847,
    "webhook_delivery": true
  }
}

Common Error Responses

Webhook limit exceeded:

{
  "success": false,
  "error": "Maximum 5 webhooks allowed per client",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Invalid URL:

{
  "success": false,
  "error": "Invalid webhook URL provided",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Webhook not found:

{
  "success": false,
  "error": "Webhook not found",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Best Practices

Use HTTPS endpoints

Required for production webhooks

Handle idempotency

Use correlation_id to deduplicate requests

Monitor webhook stats

Check /api/v2/webhooks/stats regularly

Implement proper error handling

Return appropriate HTTP status codes

Use multiple webhooks

Register backup endpoints for redundancy

Log webhook events

Keep audit trails for debugging

Synchronous API

Learn about the standard real-time intelligence endpoint for immediate results

API Examples

See request and response examples for all API endpoints and risk scenarios

Ready to Get Started?

Contact our team to obtain API credentials and begin implementing webhook-based intelligence for your automated workflows.

Our technical team will assist you with webhook integration and provide personalized API guidance