Webhooks

Fiber AI sends webhooks to notify your application when background tasks complete — no polling needed.

Overview

Many Fiber API operations (batch enrichments, lookups, searches) run in the background. Instead of polling for results, you can configure a webhook endpoint to receive a notification the moment a job finishes — whether it succeeds or fails.

Fiber uses Svix for webhook delivery, which provides:

• Automatic retries with exponential backoff

• Cryptographic signature verification

• A self-service portal to manage your endpoints

• Delivery logs and replay capabilities

Setting Up Webhooks

1. Go to fiber.ai/app/webhooks

2. Click "Set up webhooks"

3. In the portal that appears, click "Add Endpoint"

4. Enter your endpoint URL (must be HTTPS)

5. Select which event types you want to receive

6. Save — you'll start receiving webhooks immediately

Available Event Types

For the full list of event types with payload schemas and examples, see the Fiber AI Webhook Event Types page.

Below is a summary of all available events:

Enrichment

Lookup

Search

Monitoring

Other

Payload Structure

Every webhook payload includes:

• success — whether the operation succeeded or failed

• An identifier (task_id, run_id, search_id, or audience_id) — so you know which job completed

• error (only on failure) — a description of what went wrong

Example: reveal.completed

{
  "task_id": "abc123",
  "success": true,
  "emails": [
    {
      "emailAddress": "jane@company.com",
      "type": "work"
    }
  ],
  "phone_numbers": [
    {
      "phoneNumber": "+1-555-0100",
      "type": "mobile"
    }
  ],
  "linkedin_url": "https://www.linkedin.com/in/jane-doe"
}

Example: batch_contact_enrich.completed

{
  "task_id": "job_xyz789",
  "success": true,
  "total": 250,
  "completed": 237,
  "failed": 13
}

Example: Failure payload

{
  "task_id": "job_xyz789",
  "success": false,
  "total": 250,
  "completed": 100,
  "failed": 150,
  "error": "Job timed out before all items were processed"
}

Verifying Webhook Signatures

Every webhook is signed so you can verify it came from Fiber (via Svix). Each delivery includes these headers:

• svix-id — unique message ID

• svix-timestamp — Unix timestamp of when the message was sent

• svix-signature — HMAC signature to verify authenticity

Verification Libraries

Svix provides official verification libraries for all major languages:

Node.js Example

import { Webhook } from "svix";

const wh = new Webhook("whsec_your_signing_secret");

app.post("/webhooks/fiber", (req, res) => {
  try {
    const payload = wh.verify(req.body, {
      "svix-id": req.headers["svix-id"],
      "svix-timestamp": req.headers["svix-timestamp"],
      "svix-signature": req.headers["svix-signature"],
    });

    // payload is verified — process it
    console.log("Received webhook:", payload);
    res.status(200).send("OK");
  } catch (err) {
    console.error("Webhook verification failed:", err);
    res.status(400).send("Invalid signature");
  }
});

Python Example

from svix.webhooks import Webhook

wh = Webhook("whsec_your_signing_secret")

@app.post("/webhooks/fiber")
def handle_webhook(request):
    try:
        payload = wh.verify(request.body, request.headers)
        # payload is verified — process it
        print("Received webhook:", payload)
        return "OK", 200
    except Exception as e:
        print("Webhook verification failed:", e)
        return "Invalid signature", 400

You can find your signing secret in the webhook portal (click on your endpoint, then "Signing Secret").

Retry Behavior

If your endpoint returns a non-2xx status code (or doesn't respond within 30 seconds), Svix will retry the delivery with exponential backoff:

After all retries are exhausted, the message is marked as failed. You can manually retry any failed delivery from the webhook portal.

Testing Webhooks

Option 1: Use webhook.site

1. Go to webhook.site and copy your unique URL

2. Add it as an endpoint in the Fiber webhook portal

3. Trigger an async operation (e.g., start a batch enrichment)

4. Watch the payload appear on webhook.site in real time

Option 2: Use the "Send Example" button

In the Fiber webhook portal, click on an event type to see a "Send Example" button that delivers a test payload to your configured endpoint.

Option 3: Use the Svix CLI

svix listen http://localhost:3000/webhooks/fiber

This creates a temporary tunnel so Svix can deliver to your local development server.

Resources

• Event Types & Schemas — Full list with payload schemas and examples

• Svix Receiving Guide — Detailed guide on consuming webhooks

• Svix Verification Docs — Signature verification in all languages

• API Documentation — Full Fiber API reference

• OpenAPI Spec — Machine-readable spec (includes webhook schemas under the webhooks key)