Webhooks

Introduction

Webhooks allow Fairu to send real-time HTTP notifications to your systems when events occur. Instead of polling the API for changes, webhooks push data to your endpoint as soon as something happens—whether a file is uploaded, a license expires, or a workflow completes.

Common use cases

• Sync with external systems – Automatically update your CMS, PIM, or DAM when files change
• Trigger workflows – Start automated processes when specific events occur
• Send notifications – Alert your team via Slack, email, or other channels
• Audit logging – Track all changes to your digital assets in an external system

Quick start

1. Navigate to Settings → Webhooks in your Fairu dashboard
2. Click Create webhook
3. Enter your endpoint URL (must be HTTPS in production)
4. Select the events you want to receive
5. Configure authentication (optional but recommended)
6. Save and activate your webhook

Configuration options

When creating or editing a webhook, you can configure the following:

Events reference

Fairu supports webhooks for six entity types, each with its own set of events.

File events

Folder events

Copyright events

License events

Gallery events

Workflow events

Payload structure

Each webhook request is sent as an HTTP POST with a JSON body. Multiple events may be batched into a single request.

{
  "webhook_id": "550e8400-e29b-41d4-a716-446655440000",
  "events": [
    {
      "type": "file.created",
      "entity_type": "file",
      "entity_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "event_type": "created",
      "timestamp": "2026-02-03T12:00:00+00:00",
      "payload": {
        "entity_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
      }
    }
  ],
  "sent_at": "2026-02-03T12:00:05+00:00"
}

Field descriptions

Authentication

Fairu supports three authentication methods to secure your webhook endpoint.

None

No authentication is applied. The request is sent without any Authorization header. Only use this for testing or internal endpoints.

Basic authentication

HTTP Basic Auth sends credentials in the Authorization header.

Setup: Enter your credentials in the format username:password

The request will include:

Authorization: Basic base64(username:password)

Bearer token

A bearer token is sent in the Authorization header.

Setup: Enter your token value (without the "Bearer" prefix)

The request will include:

Authorization: Bearer your-token-here

Receiving webhooks

Here's an example of how to receive and process webhooks in Node.js with Express:

const express = require('express');
const app = express();
 
app.use(express.json());
 
app.post('/webhooks/fairu', (req, res) => {
  const { webhook_id, events, sent_at } = req.body;
 
  // Process each event
  for (const event of events) {
    console.log(`Received ${event.type} for ${event.entity_id}`);
 
    switch (event.entity_type) {
      case 'file':
        handleFileEvent(event);
        break;
      case 'folder':
        handleFolderEvent(event);
        break;
      case 'license':
        handleLicenseEvent(event);
        break;
      // ... handle other entity types
    }
  }
 
  // Respond quickly with 200 OK
  res.status(200).send('OK');
});
 
function handleFileEvent(event) {
  switch (event.event_type) {
    case 'created':
      console.log(`New file created: ${event.entity_id}`);
      break;
    case 'updated':
      console.log(`File updated: ${event.entity_id}`);
      break;
    case 'deleted':
      console.log(`File deleted: ${event.entity_id}`);
      break;
  }
}
 
app.listen(3000);

Technical details

Request format

• Method: POST
• Content-Type: application/json
• User-Agent: fairu/webhook
• Timeout: 5 seconds

Event debouncing

Events are debounced for 5 seconds to prevent overwhelming your endpoint with rapid successive changes. If the same entity triggers multiple events within this window, only the most recent state is sent.

Event batching

Multiple events may be batched into a single request. Always iterate over the events array rather than assuming a single event per request.

Delivery

Webhook requests are processed asynchronously via a queue. Events are typically delivered within a few seconds of occurring, though delivery time may vary under high load.

Best practices

Respond quickly

Your endpoint must respond within 5 seconds or the request will time out. Perform minimal processing in your webhook handler and queue any heavy work for background processing.

// Good: Respond immediately, process later
app.post('/webhooks/fairu', async (req, res) => {
  // Queue for background processing
  await queue.add('process-webhook', req.body);
 
  // Respond immediately
  res.status(200).send('OK');
});

Handle duplicate events

While rare, network issues may cause the same event to be delivered more than once. Design your webhook handler to be idempotent—processing the same event twice should have the same result as processing it once.

// Use entity_id + event_type + timestamp as a deduplication key
const eventKey = `${event.entity_id}-${event.event_type}-${event.timestamp}`;
if (await hasProcessedEvent(eventKey)) {
  return; // Already processed
}
await markEventProcessed(eventKey);

Log incoming requests

Log all incoming webhook requests for debugging and auditing. Include the full payload, timestamp, and your processing result.

Use HTTPS

Always use HTTPS endpoints in production to ensure webhook data is encrypted in transit.

Validate the source

Consider implementing additional validation such as:

• IP allowlisting (if Fairu provides static IPs)
• Checking the webhook_id matches your configured webhook

Debugging

Webhook logs

Fairu logs every webhook request, including:

• Request payload
• Response status code
• Response body (truncated)
• Duration in milliseconds

Access webhook logs in Settings → Webhooks → [Your Webhook] → Logs to troubleshoot delivery issues.

Common issues

Testing webhooks

For local development, use a tunnel service like ngrok to expose your local endpoint:

ngrok http 3000

Then use the generated HTTPS URL as your webhook endpoint.