Introduction

​

Welcome to the Webhooks API

​

Key Features

• API-first: Full CRUD plus test, delivery listing, and retry — no dashboard required.
• Signed payloads: Every delivery carries an HMAC-SHA256 signature so you can verify authenticity.
• Secret rotation: Rotate the signing secret in place without recreating the webhook.
• Event subscriptions: Subscribe each webhook to exactly the event types you care about.
• Delivery visibility: List delivery attempts with status, response code, and stored response body.
• Manual retry: Replay a failed delivery; it reuses the original event_id so you can dedupe.
• Dashboard parity: The same webhook is fully manageable from the dashboard and the API.

​

Authentication

curl -X POST "https://www.trysignalbase.com/api/v2/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_url": "https://example.com/hooks/signalbase",
    "event_types": ["funding.created", "hiring.created"],
    "filters": { "countries": "US,GB" }
  }'

​

Response Envelope

{
  "success": true,
  "data": {},
  "pagination": {},
  "meta": { "endpoint": "webhooks.create", "creditsUsed": 0 }
}

{ "success": false, "error": "Webhook not found", "code": "not_found" }

​

The Webhook Resource

{
  "id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "endpoint_url": "https://example.com/hooks/signalbase",
  "event_types": ["funding.created", "hiring.created"],
  "filters": { "countries": "US,GB" },
  "active": true,
  "created_at": "2026-05-29T10:30:00.000Z",
  "updated_at": "2026-05-29T10:30:00.000Z",
  "last_modified_by": "user_2a9f8c7b6d5e4f3a",
  "last_modified_via": "api",
  "secret": "3f9a1c7e-2b4d-4e6a-9f1b-8c2d3e4f5a6b",
  "secret_preview": "…5a6b",
  "stats": {
    "total_deliveries": 42,
    "successful_deliveries": 40,
    "failed_deliveries": 2,
    "last_success_at": "2026-05-29T12:00:00.000Z",
    "last_failure_at": "2026-05-28T09:00:00.000Z",
    "consecutive_failures": 0
  }
}

​

Event Types

• system.test — delivered only by the Send Test Event endpoint. It is accepted in event_types for convenience but never fires automatically.
• dashboard.push — delivered when a teammate uses the dashboard Push button to send selected companies/investors/contacts to a webhook. Personal data is GDPR-masked (last names masked, personal emails filtered) before delivery.

​

Filters

• Use funding (not round) to filter funding rounds. The webhook filter key names differ from the REST query params — e.g. the round-type key here is funding, and amount uses fundingAmount/acquisitionAmount ranges rather than amount_min/amount_max. A wrong key like { "round": "seed" } is ignored and you’ll receive the full firehose.
• Multiple keys combine with AND — an event must satisfy every filter to be delivered.
• Type-specific keys drop other types. If a subscription listens to several event types and you set a funding-only key (funding, roundFlavor, fundingAmount, healthScore), non-funding events (e.g. hiring.created) won’t match and won’t be delivered. Prefer one webhook per event type when using type-specific filters.

{
  "countries": "US,GB",
  "funding": "seed,series a",
  "fundingAmount": "1m-100m"
}

​

Credits & Limits

​

The Delivery Your Endpoint Receives

{
  "data": { "...": "full signal object — shape depends on event_type" },
  "event_id": "1f2e3d4c-5b6a-4790-8a1b-2c3d4e5f6071",
  "event_type": "funding.created",
  "timestamp": "2026-05-29T10:30:00.000Z"
}

​

Payload by event type

• signal — { id, type, externalId, occurredAt, discoveredAt, active }
• company — the full company object (or null for some events); headquartersCountry is an ISO-style country code
• employees — array of { id, name, title, linkedinUrl, email } (may be empty)
• sources — array of { url, sourceType, author, title, content, validationScore, validationReasoning, publishedAt }

{
  "data": {
    "signal": {
      "id": "a3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "type": "funding_round",
      "externalId": "fund_abc123",
      "occurredAt": "2026-05-29T00:00:00.000Z",
      "discoveredAt": "2026-05-29T08:15:00.000Z",
      "active": true
    },
    "company": {
      "id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "Acme AI",
      "slug": "acme-ai",
      "description": "Realtime fraud detection for fintechs.",
      "website": "https://acme.ai",
      "linkedinUrl": "https://www.linkedin.com/company/acme-ai",
      "twitterUrl": "https://x.com/acmeai",
      "logoUrl": "https://logo.clearbit.com/acme.ai",
      "industry": "Software Development",
      "subcategory": "fraud-detection",
      "foundedYear": 2021,
      "headquartersCountry": "US",
      "employeeCount": 85,
      "categories": "ai,fintech",
      "keywords": "fraud,risk,ml",
      "specialties": "fraud detection,risk scoring"
    },
    "employees": [],
    "sources": [
      {
        "url": "https://techcrunch.com/2026/05/29/acme-ai-series-b",
        "sourceType": "news_article",
        "author": "Jane Reporter",
        "title": "Acme AI raises $40M Series B",
        "content": "Acme AI today announced...",
        "validationScore": 0.92,
        "validationReasoning": "Multiple corroborating sources.",
        "publishedAt": "2026-05-29T07:00:00.000Z"
      }
    ],
    "fundingRound": {
      "roundType": "series b",
      "roundFlavor": null,
      "amount": 40000000,
      "currency": "USD",
      "announcedDate": "2026-05-29",
      "confidenceScore": 0.92,
      "verificationStatus": "verified",
      "investors": [
        { "name": "Sequoia Capital", "type": "vc", "leadInvestor": true },
        { "name": "Y Combinator", "type": "accelerator", "leadInvestor": false }
      ]
    }
  },
  "event_id": "1f2e3d4c-5b6a-4790-8a1b-2c3d4e5f6071",
  "event_type": "funding.created",
  "timestamp": "2026-05-29T08:15:00.000Z"
}

​

Verifying the Signature

import express from "express";
import crypto from "node:crypto";

const app = express();
const WEBHOOK_SECRET = "your-webhook-secret";

// express.raw keeps req.body as the raw Buffer so the HMAC matches exactly.
app.post(
  "/webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const sent = req.get("X-Webhook-Signature") ?? "";
    const expected = crypto
      .createHmac("sha256", WEBHOOK_SECRET)
      .update(req.body) // raw bytes
      .digest("hex");

    const a = Buffer.from(expected);
    const b = Buffer.from(sent);
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.status(401).send("bad signature");
    }

    const event = JSON.parse(req.body.toString("utf8"));
    // ...handle event, dedupe on event.event_id...
    res.json({ ok: true });
  },
);

app.listen(3000);

​

Delivery & Retry Contract

• Success = any HTTP 2xx from your endpoint. Any other status, or a network error, is a failure (a network error is recorded with response_status: 0).
• One attempt per event. The current release does not automatically retry failed deliveries on a schedule. Build idempotent handlers and reconcile gaps yourself.
• Manual retry is available: list failed deliveries with List Deliveries (?status=failed) and replay them with Retry Delivery.
• Idempotency: event_id (also sent as X-Webhook-ID) is stable across the original delivery and any retries, so you can safely dedupe.
• Response storage: the first 1000 characters of your response body are stored per delivery for debugging.
• Respond quickly — acknowledge with 2xx, then process asynchronously.

​

Full Lifecycle Over the API

# 1. Create (capture the secret from the response — shown only once)
curl -X POST "https://www.trysignalbase.com/api/v2/webhooks" \
  -H "Authorization: Bearer $SB_KEY" -H "Content-Type: application/json" \
  -d '{ "endpoint_url": "https://example.com/hook", "event_types": ["funding.created"] }'

# 2. List
curl "https://www.trysignalbase.com/api/v2/webhooks" -H "Authorization: Bearer $SB_KEY"

# 3. Fire a test event and verify the signature on your endpoint
curl -X POST "https://www.trysignalbase.com/api/v2/webhooks/$ID/test" \
  -H "Authorization: Bearer $SB_KEY"

# 4. Inspect failed deliveries, then retry one
curl "https://www.trysignalbase.com/api/v2/webhooks/$ID/deliveries?status=failed" \
  -H "Authorization: Bearer $SB_KEY"
curl -X POST "https://www.trysignalbase.com/api/v2/webhooks/$ID/deliveries/$DELIVERY_ID/retry" \
  -H "Authorization: Bearer $SB_KEY"

# 5. Delete (soft-delete)
curl -X DELETE "https://www.trysignalbase.com/api/v2/webhooks/$ID" \
  -H "Authorization: Bearer $SB_KEY"

​

Dashboard Parity & Migration

• Webhooks are editable in place. To change a URL or event list, use Update Webhook (or the dashboard Edit button) — you no longer need to delete and recreate. The signing secret is preserved across edits unless you pass rotate_secret: true.
• Retrieve existing config: vendors who configured webhooks through the dashboard can list and manage them immediately via List Webhooks — no migration step required. Only secret_preview is exposed for pre-existing webhooks; rotate the secret if you need a fresh full value.

​

Error Handling