Webhooks

Webhooks allow you to receive real-time notifications about the completion of document processing, instead of constantly polling the API.

How Webhooks Work

1. You specify the webhook_url when creating a document.
2. Rekognita processes the document.
3. Upon completion, Rekognita sends a POST request to your URL with the result.

Setup

Specify the webhook URL when submitting a document:

curl -X POST https://api.rekognita.com/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@invoice.pdf" \
  -F "language=en" \
  -F "webhook_url=https://your-server.com/webhooks/rekognita"

Payload Format

Rekognita sends a POST request with a JSON body:

{
  "event": "document.completed",
  "document_id": "doc_abc123",
  "status": "completed",
  "created_at": "2025-01-15T12:00:00Z",
  "completed_at": "2025-01-15T12:00:03Z",
  "result": {
    "text": "Recognized document text...",
    "confidence": 0.991,
    "pages": 1,
    "language": "en"
  }
}

Event Types

Request Verification

Each webhook includes an X-Rekognita-Signature header to verify authenticity. The signature is created using HMAC-SHA256:

import crypto from 'crypto';

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

// Middleware for Express
app.post('/webhooks/rekognita', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-rekognita-signature'] as string;
  
  if (!verifyWebhook(req.body.toString(), signature, process.env.WEBHOOK_SECRET!)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(req.body.toString());
  // Process event...
  
  res.sendStatus(200);
});

Retries

If your server does not return a 2xx code, Rekognita will retry the request:

• 1st retry — in 30 seconds
• 2nd retry — in 5 minutes
• 3rd retry — in 30 minutes
• Final retry — in 2 hours