FileRelayDocumentation
Try for Free

Webhook Events

Configure webhook endpoints to receive real-time notifications when documents are received, delivered, or fail in FileRelay.

Webhook Events

FileRelay can send real-time HTTP notifications to your application when key events occur. Webhooks enable you to build custom integrations, trigger workflows, and monitor document flow from your own systems.

Event Types

FileRelay sends webhooks for the following events:

Event Fired When
document.received A new document is received from SAP via ArchiveLink
document.forwarded A document is successfully delivered to a destination
document.failed A document delivery fails after all retry attempts

document.received

Fired immediately when FileRelay accepts a document from SAP. This event is sent before delivery to any destination begins.

document.forwarded

Fired each time a document is successfully delivered to a destination. If a document fans out to three destinations, you receive three separate document.forwarded events -- one for each successful delivery.

document.failed

Fired when delivery to a destination has exhausted all retry attempts and the document is marked as failed. Like document.forwarded, this is per-destination -- a document can trigger document.forwarded for some destinations and document.failed for others.

Webhook Payload Structure

All webhook events share a common payload structure:

{
  "id": "evt_abc123def456",
  "type": "document.received",
  "created_at": "2026-04-04T10:30:00Z",
  "workspace_id": "ws_xyz789",
  "data": {
    ...
  }
}
Field Type Description
id string Unique event ID (for idempotency)
type string Event type
created_at string ISO 8601 timestamp of the event
workspace_id string The workspace where the event occurred
data object Event-specific payload (see below)

Example Payloads

document.received

{
  "id": "evt_recv_001",
  "type": "document.received",
  "created_at": "2026-04-04T10:30:00Z",
  "workspace_id": "ws_xyz789",
  "data": {
    "document_id": "doc_a1b2c3d4",
    "doc_id": "4A3F8B2C1D7E9F0A",
    "repo_id": "Z1",
    "comp_id": "data",
    "content_type": "application/pdf",
    "size_bytes": 245780,
    "received_at": "2026-04-04T10:30:00Z"
  }
}

document.forwarded

{
  "id": "evt_fwd_002",
  "type": "document.forwarded",
  "created_at": "2026-04-04T10:30:02Z",
  "workspace_id": "ws_xyz789",
  "data": {
    "document_id": "doc_a1b2c3d4",
    "doc_id": "4A3F8B2C1D7E9F0A",
    "repo_id": "Z1",
    "destination_id": "dest_s3prod",
    "destination_name": "S3 Production Archive",
    "connector_type": "s3",
    "delivered_at": "2026-04-04T10:30:02Z",
    "path": "/2026/04/04/4A3F8B2C1D7E9F0A.pdf",
    "attempts": 1
  }
}

document.failed

{
  "id": "evt_fail_003",
  "type": "document.failed",
  "created_at": "2026-04-04T14:30:00Z",
  "workspace_id": "ws_xyz789",
  "data": {
    "document_id": "doc_x9y8z7w6",
    "doc_id": "9C1D3E5F7A2B4D6E",
    "repo_id": "Z1",
    "destination_id": "dest_sharepoint",
    "destination_name": "SharePoint Team Site",
    "connector_type": "sharepoint",
    "failed_at": "2026-04-04T14:30:00Z",
    "attempts": 5,
    "last_error": "Authentication failed: OAuth token expired and could not be refreshed."
  }
}

Configuring Webhooks

To set up a webhook endpoint:

  1. Navigate to Settings in the sidebar
  2. Select the Webhooks tab
  3. Click Add Webhook
  4. Enter the URL of your endpoint (must be HTTPS)
  5. Select which event types to subscribe to
  6. Click Save

REPLACE: Screenshot of the webhook configuration dialog with URL field and event type checkboxes

Your endpoint must:

  • Accept POST requests with a JSON body
  • Respond with a 2xx status code within 30 seconds
  • Be accessible over HTTPS

Signature Verification

Every webhook request includes a signature in the X-FileRelay-Signature header. Use this to verify that the request genuinely came from FileRelay and was not tampered with.

How It Works

FileRelay signs the request body using HMAC-SHA256 with your webhook signing secret:

X-FileRelay-Signature: sha256=a1b2c3d4e5f6...

Verifying the Signature

  1. Get the raw request body (before any JSON parsing)
  2. Compute HMAC-SHA256 using your webhook signing secret as the key
  3. Compare the computed signature with the value in X-FileRelay-Signature

Example (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const computed = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(signature)
  );
}

// In your webhook handler:
app.post('/webhooks/filerelay', (req, res) => {
  const signature = req.headers['x-filerelay-signature'];
  const isValid = verifyWebhookSignature(
    req.rawBody,
    signature,
    process.env.FILERELAY_WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.rawBody);
  // Process the event...

  res.status(200).send('OK');
});

Example (Python)

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    computed = 'sha256=' + hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(computed, signature)

Finding Your Signing Secret

Your webhook signing secret is displayed when you create the webhook endpoint. Like API keys, it is shown only once. If you lose it, you can regenerate it from the webhook settings (which invalidates the old secret).

Retry Behavior

If your endpoint does not respond with a 2xx status code within 30 seconds, FileRelay retries the webhook delivery:

Attempt Delay
1 Immediate
2 1 minute
3 5 minutes
4 30 minutes
5 2 hours

After 5 failed attempts, the webhook event is marked as failed and no further retries are made. Failed webhook deliveries are visible in the webhook settings page.

Idempotency

Each webhook event has a unique id field. Your application should use this ID to handle duplicate deliveries idempotently. If the same event is delivered more than once (due to retries or network issues), your handler should recognize the duplicate and avoid processing it again.

Best Practices

  • Always verify signatures to ensure webhook authenticity
  • Respond quickly with a 2xx status code, then process the event asynchronously. If your processing takes longer than 30 seconds, you risk timeout-triggered retries.
  • Store the event ID to handle duplicate deliveries
  • Use a queue for heavy processing (e.g., push events to a message queue and process them in a worker)
  • Monitor webhook failures in the FileRelay dashboard to catch endpoint issues early

Next Steps