Webhooks

Receive real-time notifications for key events in your Endpointwise account — key rotations, rate limit breaches, upstream errors, and more.

Event types

Configuring a webhook endpoint

Add a webhook via the dashboard or the management API:

POST /v1/webhooks
{
  "url": "https://yourapp.com/webhooks/endpointwise",
  "events": ["key.rotated", "rate_limit.exceeded", "gateway.upstream_error"],
  "signing_secret": "auto"  // Endpointwise generates a signing secret
}

Payload format

All webhook payloads follow the same envelope structure:

{
  "id": "evt_01abc",
  "type": "key.rotated",
  "created_at": "2026-04-07T14:22:00Z",
  "data": {
    "key_id": "key_xyz789",
    "key_prefix": "sk_live_a1b2...",
    "overlap_days": 14,
    "new_key_id": "key_abc123"
  }
}

Signature verification

Every webhook request includes an X-Endpointwise-Signature header for verification:

X-Endpointwise-Signature: sha256=a1b2c3d4e5f6g7h8...

Verify the signature in your webhook handler:

const crypto = require('crypto');

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

Retry policy

Endpointwise retries failed webhook deliveries with exponential backoff:

• First retry: 5 seconds
• Second retry: 30 seconds
• Third retry: 5 minutes
• Fourth retry: 1 hour
• Fifth retry: 24 hours

After 5 failed attempts, the event is marked as failed. Failed events are visible in the webhook delivery log for 7 days and can be manually re-delivered from the dashboard.