Webhook Setup & Configuration

Webhooks allow you to receive real-time notifications when events occur in your DocuRift account, such as when document processing completes or fails.

Overview

Instead of polling the API to check document status, webhooks push event data to your server immediately when something happens. This is more efficient and provides faster response times for your applications.

Benefits of using webhooks:

• Real-time notifications (no polling required)
• Reduced API calls and lower latency
• Automatic retry on delivery failures
• Secure signature verification

Prerequisites

Before configuring webhooks, ensure you have:

1. A publicly accessible HTTPS endpoint
2. The ability to receive POST requests
3. Admin or owner access to your DocuRift organization

Configuring Webhook URLs

Via Dashboard

1. Navigate to Settings > Webhooks in your DocuRift dashboard
2. Click Add Webhook Endpoint
3. Enter your endpoint URL (must be HTTPS)
4. Select the events you want to receive
5. Click Save

Via API

You can also configure webhooks programmatically:

curl -X POST https://api.docurift.com/v1/webhooks \
-H "X-API-Key: frc_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
  "url": "https://your-domain.com/webhooks/docurift",
  "events": [
    "document.processing.completed",
    "document.processing.failed"
  ],
  "active": true
}'

Response

{
"success": true,
"data": {
  "id": "wh_abc123def456",
  "url": "https://your-domain.com/webhooks/docurift",
  "events": [
    "document.processing.completed",
    "document.processing.failed"
  ],
  "secret": "whsec_abc123def456ghi789jkl012mno345pqr678",
  "active": true,
  "createdAt": "2024-01-26T10:30:00Z"
}
}

HTTPS Requirement

All webhook endpoints must use HTTPS. This ensures:

• Data is encrypted in transit
• Your endpoint is authenticated via SSL certificate
• Man-in-the-middle attacks are prevented

For local development, use a tunneling service like ngrok to expose your local server with HTTPS. See Testing Webhooks Locally for more details.

Authentication Options

Signature Verification (Recommended)

Every webhook request includes a signature in the X-DocuRift-Signature header. This signature is generated using HMAC-SHA256 with your webhook secret and the raw request body.

See Signature Verification for implementation details.

IP Allowlisting (Optional)

For additional security, you can allowlist DocuRift's webhook IP addresses:

• 34.102.136.180
• 35.186.224.42
• 34.107.188.156

Retry Policy

If your endpoint returns an error or times out, DocuRift will automatically retry delivery:

| Attempt | Delay | Total Time Elapsed | |---------|-------|-------------------| | 1st retry | 1 minute | 1 minute | | 2nd retry | 10 minutes | 11 minutes | | 3rd retry | 1 hour | ~1 hour 11 minutes |

Retry Conditions

Retries are triggered when:

• Your endpoint returns a 5xx status code
• Your endpoint returns a 429 (rate limited) status code
• The request times out (30 second timeout)
• A network error occurs

Successful Delivery

A webhook is considered successfully delivered when your endpoint returns:

• 200 OK
• 201 Created
• 202 Accepted
• 204 No Content

Endpoint Requirements

Your webhook endpoint should:

1. Accept POST requests with JSON body
2. Respond quickly (< 30 seconds)
3. Return 2xx status on success
4. Handle duplicates idempotently (webhooks may be delivered more than once)
5. Verify signatures before processing

Example Endpoint (Node.js/Express)

import express from 'express';
import crypto from 'crypto';

const app = express();

// Use raw body for signature verification
app.post('/webhooks/docurift',
express.raw({ type: 'application/json' }),
(req, res) => {
  const signature = req.headers['x-docurift-signature'];
  const timestamp = req.headers['x-docurift-timestamp'];

  // Verify signature (see verification docs)
  if (!verifySignature(req.body, signature, timestamp)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body);

  // Process event asynchronously
  processEventAsync(event);

  // Respond immediately
  res.status(200).json({ received: true });
}
);

async function processEventAsync(event) {
switch (event.type) {
  case 'document.processing.completed':
    console.log('Document completed:', event.data.documentId);
    // Handle completed document
    break;
  case 'document.processing.failed':
    console.log('Document failed:', event.data.documentId);
    // Handle failure
    break;
}
}

app.listen(3000);

Managing Webhooks

List All Webhooks

curl -X GET https://api.docurift.com/v1/webhooks \
-H "X-API-Key: frc_your_api_key_here"

Update a Webhook

curl -X PATCH https://api.docurift.com/v1/webhooks/wh_abc123def456 \
-H "X-API-Key: frc_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
  "events": ["document.processing.completed"],
  "active": true
}'

Delete a Webhook

curl -X DELETE https://api.docurift.com/v1/webhooks/wh_abc123def456 \
-H "X-API-Key: frc_your_api_key_here"

Rotate Webhook Secret

If your webhook secret is compromised, rotate it immediately:

curl -X POST https://api.docurift.com/v1/webhooks/wh_abc123def456/rotate-secret \
-H "X-API-Key: frc_your_api_key_here"

Best Practices

1. Verify all signatures - Never trust webhook data without verification
2. Respond immediately - Return 200 before processing to avoid timeouts
3. Handle idempotently - Webhooks may be delivered multiple times
4. Store the event ID - Use event.id to deduplicate events
5. Log all events - Maintain an audit trail for debugging
6. Monitor failures - Set up alerts for failed webhook deliveries
7. Use queues - Process webhooks asynchronously using a job queue

Next Steps

• Webhook Event Types - Learn about all available events
• Signature Verification - Implement secure verification
• Testing Webhooks - Test locally and debug issues