Webhooks API

All webhook endpoints require authentication via X-Api-Key.

Create Webhook

POST /api/v1/webhooks

Request Body

Field	Type	Required	Description
url	string	Yes	HTTPS URL to deliver events to
secret	string	Yes	Secret for HMAC-SHA256 signing
events	string[]	Yes	Event types: paste.created, paste.deleted, paste.expired

Example

curl -X POST https://paste.example.com/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: pb_your-key" \
  -d '{
    "url": "https://example.com/webhook",
    "secret": "my-secret",
    "events": ["paste.created", "paste.deleted"]
  }'

Delivery Headers

Each delivery includes:

Header	Description
X-Pastebox-Event	Event type
X-Pastebox-Delivery	Unique delivery ID
X-Pastebox-Signature-256	HMAC-SHA256 hex digest of the body

Verifying Signatures

const crypto = require('crypto');

function verify(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

List Webhooks

GET /api/v1/webhooks

Get Webhook

GET /api/v1/webhooks/:id

Update Webhook

PATCH /api/v1/webhooks/:id

Delete Webhook

DELETE /api/v1/webhooks/:id

Test Webhook

POST /api/v1/webhooks/:id/test

Sends a test delivery to verify the webhook URL is reachable.

Retry Policy

Failed deliveries are retried with exponential backoff:

Attempt	Delay
1	20 seconds
2	40 seconds
3	80 seconds
4	160 seconds
5	320 seconds

After 5 failed attempts, the delivery is marked as failed.