Skip to content
RosetRosetDocs
SDK
RosetRosetDocs

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

EventWhen it fires
file.createdA new file record was created via upload
file.processing.startedThe extraction job began processing
file.processing.completedExtraction finished successfully and variants are available
file.processing.failedExtraction failed (check the job for error details)
file.variant.readyA new variant (markdown, embeddings) is available on the file
file.deletedA file and its variants were deleted
connection.syncedA storage connection finished syncing metadata from the bucket

Create a Webhook

python
import os
from roset import Client
 
client = Client(api_key=os.getenv("ROSET_API_KEY"))
 
# Register an endpoint for processing lifecycle events
webhook = client.webhooks.create(
    url="https://example.com/roset-webhook",
    events=["file.processing.completed", "file.processing.failed"],
)
 
print(webhook["id"])      # "wh-abc123"
print(webhook["secret"])  # Save this -- used to verify signatures

Payload Format

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

json
{
  "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.

python
import hashlib
import hmac
 
def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(signature, expected)
Always Verify Signatures

Verify the signature on every webhook delivery to confirm it originated from Roset and was not tampered with in transit.

Retry Policy

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

AttemptDelay
1st retry~1 minute
2nd retry~5 minutes
3rd retry~30 minutes

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

python
# List all registered webhooks
result = client.webhooks.list()
 
# Update which events a webhook subscribes to
client.webhooks.update("wh-abc123", events=["file.processing.completed"])
 
# Send a test event to verify your endpoint
client.webhooks.test("wh-abc123")
 
# View delivery history for debugging
deliveries = client.webhooks.deliveries("wh-abc123")
 
# Delete a webhook
client.webhooks.delete("wh-abc123")

Next Steps

Edit this page on GitHub