Skip to main content

​
Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur in your Monk account. Instead of polling the API for changes, webhooks push data to your server as events happen.

​
How Webhooks Work

  1. You configure a webhook endpoint URL in your Settings
  2. When an event occurs (e.g., an invoice is created), Monk sends an HTTP POST request to your endpoint
  3. Your server processes the event and returns a 2xx response to acknowledge receipt
Webhooks are sent asynchronously and may arrive out of order. Use the id field and timestamps to handle deduplication and ordering.

​
Setting Up Webhooks

​
1. Create an Endpoint

Navigate to Settings → Webhooks in your Monk dashboard and click Add Endpoint. Provide:
  • URL: Your HTTPS endpoint that will receive webhook events
  • Events: Select which events to subscribe to

​
2. Get Your Signing Secret

After creating the endpoint, copy the signing secret. You’ll use this to verify webhook signatures.
Store your signing secret securely. Never expose it in client-side code.

​
3. Handle Incoming Webhooks

Your endpoint should:
  1. Verify the webhook signature
  2. Process the event
  3. Return a 2xx status code quickly
// Example Express.js handler
app.post('/webhooks/monk', (req, res) => {
  const payload = req.body;
  const signature = req.headers['x-monk-signature'];

  // Verify signature (see Verification docs)
  if (!verifySignature(payload, signature, SIGNING_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  const event = req.headers['x-monk-event'];
  console.log(`Received ${event}:`, payload);

  // Acknowledge receipt
  res.status(200).send('OK');
});

​
Webhook Headers

Each webhook request includes these headers:
HeaderDescription
Content-TypeAlways application/json
User-AgentMonk-Webhook/1.0
X-Monk-EventEvent type (e.g., invoice.created)
X-Monk-Delivery-IdUnique delivery ID for idempotency
X-Monk-SignatureSignature for verification

​
Retry Policy

If your endpoint returns a non-2xx response or times out, Monk will retry delivery:
  • Total attempts: 6 (1 initial + 5 retries)
  • Backoff: Exponential with jitter (~15s, 30s, 1m, 2m, 5m)
  • Timeout: 10 seconds per attempt
After all retries are exhausted, the delivery is marked as failed.

​
Best Practices

Webhook requests timeout after 10 seconds. Return a 200 response immediately, then process the event asynchronously in a background job if needed.
Use the X-Monk-Delivery-Id header or the payload id field to detect and ignore duplicate deliveries.
Never trust webhook payloads without verifying the signature. This prevents spoofed requests.
We enforce HTTPS endpoints to ensure webhook payloads are encrypted in transit.

​
Next Steps

Webhook Events

See all available events and their payload structures

Signature Verification

Learn how to verify webhook signatures