Webhooks

Webhooks

Webhooks allow you to receive real-time HTTP notifications when specific events occur in your R2 Bucket Manager. This enables you to build integrations, automate workflows, and synchronize data with external systems.

Overview

When a configured event occurs (e.g., a file is uploaded or a bucket is created), the R2 Bucket Manager sends a POST request to your specified URL with a JSON payload containing details about the event.

Configuration

To manage webhooks, navigate to the Webhooks tab in the main navigation.

Creating a Webhook

1. Click the Add Webhook button.
2. Name: Enter a descriptive name for the webhook (e.g., "Slack Notification").
3. URL: Enter the endpoint URL that will receive the POST request. This must be a valid HTTP/HTTPS URL.
4. Secret (Optional): Enter a secret key to sign the webhook payload. This allows you to verify that the request originated from your R2 Manager. highly recommended for production.
5. Events: Select the events that should trigger this webhook.
6. Enabled: Toggle to enable or disable the webhook immediately.
7. Click Create to save.

Managing Webhooks

• Edit: Click the edit (pencil) icon to modify an existing webhook.
• Delete: Click the trash icon to permanently remove a webhook.
• Enable/Disable: Use the toggle button to quickly pause or resume notifications without deleting the configuration.
• Test: Click the Test button to send a mock event to your endpoint and verify connectivity.

Supported Events

The following 15 events are available for subscription:

Event Type	Description
file_upload	Triggered when a file is successfully uploaded to a bucket.
file_download	Triggered when a file is downloaded from a bucket.
file_delete	Triggered when a file is deleted from a bucket.
file_move	Triggered when a file is moved between buckets or folders.
file_copy	Triggered when a file is copied to another bucket or folder.
file_rename	Triggered when a file is renamed.
folder_create	Triggered when a new folder is created.
folder_delete	Triggered when a folder is deleted.
bucket_create	Triggered when a new bucket is created.
bucket_delete	Triggered when a bucket is deleted.
bucket_rename	Triggered when a bucket is renamed.
job_completed	Triggered when a bulk job (e.g., bulk delete, multi-bucket download) finishes successfully.
job_failed	Triggered when a bulk job fails or encounters errors.
migration_completed	Triggered when a database migration is successfully applied.
migration_failed	Triggered when a database migration fails.

Payload Structure

All webhooks are sent as POST requests with a Content-Type: application/json header. The payload follows a standard structure:

{
  "id": "evt_123456789",
  "event": "file_upload",
  "timestamp": "2023-10-27T10:30:00.000Z",
  "data": {
    "bucket": "my-images",
    "key": "uploads/avatar.jpg",
    "size": 1024,
    "contentType": "image/jpeg",
    "etag": "\"d41d8cd98f00b204e9800998ecf8427e\""
  }
}

Data Object by Event Type

file_upload / file_delete

{
  "bucket": "string",
  "key": "string",
  "size": "number (optional)",
  "contentType": "string (optional)",
  "etag": "string (optional)"
}

bucket_create / bucket_delete

{
  "bucket": "string"
}

job_completed / job_failed

{
  "jobId": "string",
  "type": "bulk_delete",
  "status": "completed",
  "processedFiles": 150,
  "errorCount": 0
}

Security & Verification

If you configured a Secret, R2 Bucket Manager will sign the webhook payload using HMAC-SHA256. The signature is included in the X-Webhook-Signature header.

Verifying the Signature

To verify the webhook originated from your R2 Manager:

1. Retrieve the X-Webhook-Signature header from the request.
2. Retrieve the raw request body.
3. Compute the HMAC-SHA256 hash of the raw body using your configured Secret.
4. Hex-encode the hash.
5. Compare your computed signature with the header value. They should match exactly.

Example Code (Node.js)

const crypto = require("crypto");

function verifyWebhook(payload, signatureHeader, secret) {
  const computedSignature = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(computedSignature),
  );
}

Example Code (Python)

import hmac
import hashlib

def verify_webhook(payload, signature_header, secret):
    computed_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(computed_signature, signature_header)

Troubleshooting

• 404 Not Found: Ensure your endpoint URL is correct and accessible from the public internet (or Cloudflare Workers environment).
• Signature Mismatch: Verify you are using the exact secret key and computing the hash on the raw request body string, not the parsed JSON object.
• Timeouts: Your webhook endpoint must respond within 10 seconds. We recommend processing the data asynchronously.