Overview Webhooks are a planned feature and not yet implemented. This documentation describes the intended functionality.
Webhooks enable real-time notifications when jobs complete, fail, or encounter issues. You can register webhook endpoints to receive POST requests with event data.
Register Webhook Request (Planned)
Response (201) (Planned)
POST /v1/webhooks Authorization: Bearer < toke n > Content-Type: application/json { "url" : "https://example.com/webhooks/adapt", "events" : [ "job.completed" , "job.failed"], "secret" : "webhook_secret_123" }
Request Body HTTPS endpoint to receive webhook POST requests
Array of event types to subscribe to:
job.completed: Job finished successfullyjob.failed: Job failed with errorsjob.cancelled: Job was cancelledtask.failed: Individual task failed (high volume) Secret key for HMAC signature verification
Response Fields Unique webhook identifier
Registered webhook endpoint URL
Whether webhook is currently enabled
Webhook Events Job Completed Event { "event" : "job.completed" , "timestamp" : "2023-05-18T12:34:56Z" , "data" : { "job_id" : "job_123abc" , "domain" : "example.com" , "status" : "completed" , "total_tasks" : 150 , "completed_tasks" : 150 , "failed_tasks" : 0 , "stats" : { "avg_response_time" : 234 , "cache_hit_ratio" : 0.85 , "total_bytes" : 2048576 }, "created_at" : "2023-05-18T12:00:00Z" , "completed_at" : "2023-05-18T12:34:56Z" }, "signature" : "sha256=..." }
Job Failed Event { "event" : "job.failed" , "timestamp" : "2023-05-18T12:34:56Z" , "data" : { "job_id" : "job_123abc" , "domain" : "example.com" , "status" : "failed" , "error_message" : "Connection timeout" , "total_tasks" : 150 , "completed_tasks" : 45 , "failed_tasks" : 105 , "created_at" : "2023-05-18T12:00:00Z" , "failed_at" : "2023-05-18T12:34:56Z" }, "signature" : "sha256=..." }
Job Cancelled Event { "event" : "job.cancelled" , "timestamp" : "2023-05-18T12:34:56Z" , "data" : { "job_id" : "job_123abc" , "domain" : "example.com" , "status" : "cancelled" , "total_tasks" : 150 , "completed_tasks" : 45 , "created_at" : "2023-05-18T12:00:00Z" , "cancelled_at" : "2023-05-18T12:34:56Z" }, "signature" : "sha256=..." }
Webhook Signature Verification Each webhook request includes an HMAC-SHA256 signature in the signature field. Verify this signature to ensure the request came from Adapt.
Verification Process
Extract the signature from the signature field
Compute HMAC-SHA256 of the raw request body using your webhook secret
Compare the computed signature with the received signature
Example (Node.js) const crypto = require ( 'crypto' ); function verifyWebhookSignature ( payload , signature , secret ) { const expectedSignature = crypto . createHmac ( 'sha256' , secret ) . update ( JSON . stringify ( payload )) . digest ( 'hex' ); return `sha256= ${ expectedSignature } ` === signature ; }
Example (Python) import hmac import hashlib import json def verify_webhook_signature ( payload , signature , secret ): expected_signature = hmac.new( secret.encode( 'utf-8' ), json.dumps(payload).encode( 'utf-8' ), hashlib.sha256 ).hexdigest() return f "sha256= { expected_signature } " == signature
List Webhooks Request (Planned)
Response (200) (Planned)
GET /v1/webhooks Authorization: Bearer < toke n >
Update Webhook Request (Planned)
Response (200) (Planned)
PUT /v1/webhooks/{webhook_id} Authorization: Bearer < toke n > Content-Type: application/json { "events" : [ "job.completed" ], "is_active" : true }
Request Body Update subscribed event types
Enable or disable webhook
Delete Webhook Request (Planned)
Response (200) (Planned)
DELETE /v1/webhooks/{webhook_id} Authorization: Bearer < toke n >
Best Practices Handle Retries Adapt will retry failed webhook deliveries with exponential backoff:
Initial attempt: immediate
1st retry: after 1 minute
2nd retry: after 5 minutes
3rd retry: after 15 minutes
Final retry: after 1 hour
Your endpoint should:
Return 2xx status code to acknowledge receipt
Process webhooks idempotently (same webhook may be delivered multiple times)
Respond quickly (under 5 seconds)
Security
Always verify webhook signatures
Use HTTPS endpoints only
Keep webhook secrets secure
Implement rate limiting on your endpoint
Error Handling app . post ( '/webhooks/adapt' , async ( req , res ) => { try { // Verify signature first if ( ! verifyWebhookSignature ( req . body , req . body . signature , SECRET )) { return res . status ( 401 ). send ( 'Invalid signature' ); } // Respond immediately res . status ( 200 ). send ( 'OK' ); // Process webhook asynchronously await processWebhookAsync ( req . body ); } catch ( error ) { console . error ( 'Webhook processing error:' , error ); res . status ( 500 ). send ( 'Internal error' ); } });
Roadmap Webhooks are planned for implementation in Q2 2024. The feature will include:
Full CRUD operations for webhook management
Automatic retry logic with exponential backoff
Webhook delivery logs and debugging tools
Test webhook functionality
Support for additional event types
Check the Adapt GitHub repository for updates on webhook availability.