Webhooks

Webhooks

D1 Manager supports webhook notifications for key database events. Configure webhooks to send HTTP POST requests to external services like Slack, Discord, or custom monitoring endpoints.

Overview

Webhooks allow you to:

• Receive real-time notifications when database operations occur
• Integrate with external monitoring and alerting systems
• Trigger automated workflows based on database events
• Track failures and issues proactively

Supported Events

D1 Manager provides 13 streamlined webhook event types organized by category:

Database Lifecycle

Event	Trigger	Payload
database_create	Database created	database_id, database_name, user_email
database_delete	Database deleted	database_id, database_name, user_email

Table DDL Operations

Event	Trigger	Payload
table_create	Table created (including clone)	database_id, database_name, table_name, user_email
table_delete	Table dropped	database_id, database_name, table_name, user_email
table_update	Table altered (rename, columns, indexes)	database_id, database_name, table_name, description, user_email

R2 Snapshot Lifecycle

Event	Trigger	Payload
backup_complete	R2 backup snapshot completed	database_id, database_name, backup_path, size_bytes, user_email
restore_complete	Backup restored from R2	database_id, database_name, backup_path, restored_rows, user_email

Data Transfer Operations

Event	Trigger	Payload
import_complete	SQL/JSON import completed	database_id, database_name, num_queries, user_email
export_complete	SQL/JSON export completed	database_id, database_name, size_bytes, format, user_email

DDL Query Execution

Event	Trigger	Payload
schema_change	DDL query executed (CREATE/ALTER/DROP)	database_id, database_name, ddl_type, object_type, object_name, user_email

Bulk Operations

Event	Trigger	Payload
bulk_delete_complete	Bulk row deletion completed	database_id, database_name, table_name, rows_deleted, user_email

Job Lifecycle

Event	Trigger	Payload
job_failed	Any tracked operation fails	job_id, job_type, error_message, database_id, user_email
batch_complete	Bulk operation completes	job_type, total_items, success_count, failed_count, user_email

Backward Compatibility

Legacy event aliases are supported for backward compatibility:

Legacy Event	Maps To
database_export	export_complete
database_import	import_complete

Configuration

Using the UI

1. Navigate to the Webhooks tab in D1 Manager
2. Click Add Webhook
3. Fill in the configuration:
   • Name: A descriptive name for the webhook
   • URL: The endpoint that will receive webhook POST requests
   • Secret (optional): A shared secret for HMAC signature verification
   • Events: Select which events should trigger this webhook
   • Enabled: Toggle to enable/disable the webhook

Testing Webhooks

Before going live, use the Test button to send a test payload to your endpoint. The test result will show:

• Whether the request succeeded
• The HTTP status code
• Any error message

Payload Format

All webhook payloads follow this structure:

{
  "event": "table_create",
  "timestamp": "2026-01-06T12:00:00.000Z",
  "data": {
    "database_id": "abc-123",
    "database_name": "my-database",
    "table_name": "users",
    "user_email": "user@example.com"
  }
}

Headers

Header	Description
Content-Type	application/json
User-Agent	D1-Manager-Webhook/1.0
X-Webhook-Event	The event type (e.g., table_create)
X-Webhook-Signature	HMAC-SHA256 signature (if secret is configured)

Security

HMAC Signature Verification

If you configure a secret for your webhook, D1 Manager will include an X-Webhook-Signature header with each request. This allows you to verify that the request genuinely came from D1 Manager.

Signature format: sha256=<hex-encoded-hmac>

Example verification (Node.js):

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSig = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSig)
  );
}

// In your webhook handler:
const isValid = verifyWebhookSignature(
  req.rawBody,
  req.headers['x-webhook-signature'],
  'your-webhook-secret'
);

API Reference

Endpoint	Method	Description
/api/webhooks	GET	List all webhooks
/api/webhooks	POST	Create a new webhook
/api/webhooks/:id	GET	Get a single webhook
/api/webhooks/:id	PUT	Update a webhook
/api/webhooks/:id	DELETE	Delete a webhook
/api/webhooks/:id/test	POST	Send a test webhook

Create Webhook

Request:

POST /api/webhooks
{
  "name": "Slack Notifications",
  "url": "https://hooks.slack.com/services/xxx/yyy/zzz",
  "secret": "my-secret",
  "events": ["database_create", "job_failed", "backup_complete"],
  "enabled": true
}

Response:

{
  "webhook": {
    "id": "whk_abc123",
    "name": "Slack Notifications",
    "url": "https://hooks.slack.com/services/xxx/yyy/zzz",
    "secret": "my-secret",
    "events": "[\"database_create\",\"job_failed\",\"backup_complete\"]",
    "enabled": 1,
    "created_at": "2026-01-06T12:00:00Z",
    "updated_at": "2026-01-06T12:00:00Z"
  }
}

Integration Examples

Slack

Use a Slack Incoming Webhook URL:

https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX

Note: Slack expects a specific format. You may need a middleware to transform D1 Manager's payload to Slack's format.

Discord

Use a Discord Webhook URL:

https://discord.com/api/webhooks/XXXXX/YYYYY

Similar to Slack, Discord has its own payload format that may require transformation.

Custom Services

Any HTTP endpoint that accepts POST requests can receive webhooks. Ensure your endpoint:

• Responds with a 2xx status code on success
• Processes requests within a reasonable timeout
• Handles potential retries gracefully

Troubleshooting

Webhook not firing

1. Check that the webhook is Enabled
2. Verify the event type is selected
3. Use the Test button to check connectivity
4. Check your endpoint's logs for incoming requests

Signature verification failing

1. Ensure you're using the raw request body (not parsed JSON)
2. Verify the secret matches exactly
3. Check for encoding issues with special characters

Timeout errors

Webhook requests have a timeout. If your endpoint takes too long to respond:

• Return a 2xx status quickly, then process asynchronously
• Optimize your endpoint's response time
• Consider using a queue for heavy processing

Schema

Webhooks are stored in the webhooks table in the metadata database:

CREATE TABLE IF NOT EXISTS webhooks (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  url TEXT NOT NULL,
  secret TEXT,
  events TEXT NOT NULL, -- JSON array of event types
  enabled INTEGER DEFAULT 1,
  created_at TEXT DEFAULT (datetime('now')),
  updated_at TEXT DEFAULT (datetime('now'))
);

---

See also:

• Observability - OpenTelemetry integration for traces and logs
• Job History - Track all database operations
• API Reference - Complete API documentation