For the complete documentation index, see llms.txt. This page is also available as Markdown.

Webhooks

Webhooks let your service react in real time to events on the Heron Intelligence platform — no polling required.

Supported events

Event
Fires when

research_request.transcript_added

A new transcript is delivered against one of your projects. Fires once per transcript — a project with 10 transcripts triggers the event 10 times.

evasion.analysis.published

An earnings call receives its first evasion verdict. See Evasion.

evasion.analysis.revised

A new version of an evasion analysis replaces an earlier verdict. Carries both ratios and the id of the version it replaced.

Subscribing

Register a URL with POST /api/v1/webhooks. The response contains a signing secret that is shown exactly once — store it immediately. If lost, delete the subscription and create a new one.

curl -X POST https://api.heron-intelligence.com/api/v1/webhooks \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/hooks/heron",
    "event_type": "research_request.transcript_added"
  }'

Substitute any event from the table above — one subscription per event type.

{
  "id": "9c2c…",
  "url": "https://your-app.example.com/hooks/heron",
  "event_type": "research_request.transcript_added",
  "is_active": true,
  "created_at": "2026-05-26T14:00:00Z",
  "secret": "Xz9k…"
}

Create Webhook Subscription

post

Register a new webhook URL for the authenticated client.

The signing secret in the response is shown exactly once — store it immediately. It cannot be retrieved later. If lost, delete the subscription and create a new one.

Every delivery to the registered URL is signed with HMAC-SHA256 of the raw request body using this secret and sent in the X-Webhook-Signature: sha256=<hex> header.

Supported events: research_request.transcript_added — fires once per transcript added to one of your projects.

Headers: x-api-key (required)

Header parameters
x-api-keystringRequired

Client API Key

Body

Payload to register a new webhook subscription.

urlstring · uri · min: 1 · max: 2083Required

HTTPS URL that will receive POST deliveries.

event_typestringRequired

Event the subscription listens for. Currently supported: research_request.transcript_added.

Responses
201

Successful Response

application/json

Returned only on creation — includes the signing secret exactly once. Store it immediately; it cannot be retrieved later.

idstring · uuidRequired
urlstringRequired
event_typestringRequired
is_activebooleanRequired
created_atstring · date-timeRequired
secretstringRequired

HMAC-SHA256 signing secret. Returned only here and cannot be retrieved later.

post/api/v1/webhooks
POST /api/v1/webhooks HTTP/1.1
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 49

{
  "url": "https://example.com",
  "event_type": "text"
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "url": "text",
  "event_type": "text",
  "is_active": true,
  "created_at": "2026-01-01T00:00:00.000Z",
  "secret": "text"
}

Listing your subscriptions

The secret is intentionally omitted from list and get responses — it cannot be retrieved after creation.

List Webhook Subscriptions

get

List the webhook subscriptions registered for the authenticated client. The secret field is intentionally omitted — it is only returned at creation time.

Headers: x-api-key (required)

Header parameters
x-api-keystringRequired

Client API Key

Responses
200

Successful Response

application/json

Webhook subscription as returned by list/get. The signing secret is omitted on purpose — it is shown only at creation.

idstring · uuidRequired
urlstringRequired
event_typestringRequired
is_activebooleanRequired
created_atstring · date-timeRequired
get/api/v1/webhooks
GET /api/v1/webhooks HTTP/1.1
x-api-key: text
Accept: */*
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "url": "text",
    "event_type": "text",
    "is_active": true,
    "created_at": "2026-01-01T00:00:00.000Z"
  }
]

Deleting a subscription

Delete Webhook Subscription

delete

Delete a webhook subscription owned by the authenticated client. Returns 404 if the subscription does not exist or belongs to a different client.

Headers: x-api-key (required)

Path parameters
subscription_idstring · uuidRequired
Header parameters
x-api-keystringRequired

Client API Key

Responses
204

Successful Response — no body.

No content

delete/api/v1/webhooks/{subscription_id}
DELETE /api/v1/webhooks/{subscription_id} HTTP/1.1
x-api-key: text
Accept: */*

No content

Delivery payload

Every request is a POST with Content-Type: application/json and these headers:

Header
Value

X-Webhook-Event

The event type (e.g. research_request.transcript_added).

X-Webhook-Signature

sha256=<hex> — HMAC-SHA256 of the raw request body with your secret.

Body shape for research_request.transcript_added:

  • event_id is stable per delivery — use it to deduplicate on your side if you receive the same event twice (it can happen during retries if your 2xx response gets lost on the wire).

  • transcript_id is resolvable via GET /api/v1/interviews/{transcript_id}.

  • research_id is resolvable via GET /api/v1/operations/research-request/{research_id}.

Evasion events

Both carry event, event_id and created_at like every other delivery. Neither carries a transcript_id: an evasion analysis identifies its call by company, date and title, and the API serves no transcript. See Evasion.

Body shape for evasion.analysis.published — a call's first verdict:

Body shape for evasion.analysis.revised — a new version replaced an earlier verdict:

  • analysis_id is resolvable via GET /api/v1/evasion/analyses/{analysis_id}.

  • company_id is resolvable via GET /api/v1/companies/{company_id}.

  • revised is not an edge case. A call can be re-analysed, so a subscriber that treats every event as new data ends up holding two contradictory verdicts for one call. Key your store on analysis_id and retire parent_analysis_id — the older version it replaced — when a revision arrives.

  • Both ratios are on the revised payload so you can see what moved without a round trip. They are ratios in 0..1, never percentages.

Verifying the signature

Always verify the signature before trusting the payload. Compute HMAC-SHA256 of the raw request body using your stored secret and compare it constant-time against the incoming X-Webhook-Signature header.

Python

Node.js

Important: compute the HMAC over the raw request body, not over a parsed-then-restringified version — JSON re-serialization can change byte order or whitespace and invalidate the signature.

Delivery behavior

Aspect
Behavior

Attempts

Up to 3 per event.

Backoff

Exponential — 1s, 4s, 16s between attempts.

Retry on

Any 5xx, 408, 429, or transport errors (timeout, DNS, TCP reset).

Terminal failure on

Any other 4xx. No retries.

Success condition

Any 2xx. We do not parse the response body.

Timeout per attempt

10 seconds.

A 2xx is the only success signal — once received, the delivery is considered complete and no further attempts are made.

What you should do on your end

  • Respond 2xx quickly (under a few seconds). Acknowledge the event, then process it asynchronously. If you do the work inline and exceed the 10-second timeout, the delivery will retry and you may double-process.

  • Deduplicate by event_id. Treat the receipt of the same event_id twice as a no-op.

  • Handle out-of-order delivery. Two events for the same project can arrive out of order — never assume order.

  • Store the raw body before verifying. If you parse JSON before checking the signature, you cannot recompute the HMAC over the bytes that were actually sent.

Limitations and roadmap

A few constraints worth knowing as you build against this V1 surface:

  • No secret rotation endpoint yet. If you need to rotate a secret, delete and re-create the subscription.

  • No replay endpoint. Failed deliveries are stored server-side with the full payload, but there is no consumer-facing endpoint to re-trigger them. Open a ticket if you need a replay.

  • No event-type discovery endpoint. The supported events are documented here statically; subscribing to an unrecognized event_type does not error at registration but will never fire.

  • No per-subscription rate limiting. A slow receiver under heavy event volume will hold open many concurrent connections from our side.

We will publish a changelog entry when any of these change.

Last updated