Webhooks

Webhooks are HTTP callbacks that Roset sends to your application when processing events occur. Instead of polling the API to check if a file has finished processing, register a webhook endpoint and Roset will POST event payloads to it in real time.

This is the recommended way to react to processing completion in production applications.

Event Types#

Create a Webhook#

Payload Format#

Each delivery sends a JSON payload with an event type, timestamp, and event-specific data:

{
  "id": "evt-123",
  "type": "file.processing.completed",
  "timestamp": "2025-06-15T10:30:00Z",
  "data": {
    "file_id": "abc-123",
    "space": "default",
    "filename": "report.pdf",
    "status": "completed"
  }
}

Verify Signatures#

Every webhook delivery includes an X-Roset-Signature header containing an HMAC SHA-256 signature of the request body. Use your webhook secret (returned when you created the webhook) to verify authenticity.

import crypto from 'crypto';
 
// Verify that the webhook payload was sent by Roset
function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

Retry Policy#

Failed deliveries (non-2xx responses or timeouts) are retried up to 3 times with exponential backoff:

After 3 failed attempts, the delivery is marked as failed. You can view failed deliveries in the console or via the deliveries endpoint.

Manage Webhooks#

Next Steps#

• API Reference -- full webhook endpoint documentation.
• Storage Connections -- connect your cloud storage buckets.