Webhooks
Webhooks let your service react in real time to events on the Heron Intelligence platform — no polling required.
Supported events
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…"
}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)
Client API Key
Payload to register a new webhook subscription.
HTTPS URL that will receive POST deliveries.
Event the subscription listens for. Currently supported: research_request.transcript_added.
Successful Response
Returned only on creation — includes the signing secret exactly once. Store it immediately; it cannot be retrieved later.
HMAC-SHA256 signing secret. Returned only here and cannot be retrieved later.
Invalid or missing API key.
Validation Error
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 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)
Client API Key
Successful Response
Webhook subscription as returned by list/get. The signing secret is omitted on purpose — it is shown only at creation.
Invalid or missing API key.
Validation Error
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 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)
Client API Key
Successful Response — no body.
No content
Invalid or missing API key.
Subscription not found.
Validation Error
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:
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_idis stable per delivery — use it to deduplicate on your side if you receive the same event twice (it can happen during retries if your2xxresponse gets lost on the wire).transcript_idis resolvable viaGET /api/v1/interviews/{transcript_id}.research_idis resolvable viaGET /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_idis resolvable viaGET /api/v1/evasion/analyses/{analysis_id}.company_idis resolvable viaGET /api/v1/companies/{company_id}.revisedis 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 onanalysis_idand retireparent_analysis_id— the older version it replaced — when a revision arrives.Both ratios are on the
revisedpayload so you can see what moved without a round trip. They are ratios in0..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
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
2xxquickly (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 sameevent_idtwice 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_typedoes 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