Filing webhook API: disclosure events, pushed
A filing webhook API pushes an HTTP request to your endpoint when a new regulatory disclosure is recorded, rather than making you poll for it. For filing data the case for push is straightforward: disclosures arrive in bursts tied to exchange and regulator schedules, so polling on a fixed interval is either too slow at the peak or wasted for most of the day. What separates a usable filing webhook API from a fragile one is signing, delivery semantics and retry behaviour you can audit. This page covers those. It is not investment advice.
Definition
A filing webhook API
is an interface that delivers an HTTP POST to a URL you control whenever a new regulatory disclosure is recorded, carrying the event type, a stable event id and the disclosure payload, signed so the receiver can verify the sender.
What a filing webhook API has to get right
Five things, and they are the ones to test before you build on any provider:
- Signature verification over the raw body. The receiver must be able to recompute an HMAC from the bytes it received. If a provider signs a re-serialised payload, verification breaks the moment your framework reorders JSON keys.
- A replay window. A timestamp inside the signature, with a tolerance, so a captured payload cannot be replayed indefinitely.
- Stable event ids. The same logical event must carry the same id across retries, so deduplication works.
- A retry policy with an end state. Exponential backoff, a maximum attempt count, and a dead-letter state you can query. Silent infinite retries and silent dropping are both wrong.
- Secret rotation without downtime. A window during which both the old and new secret produce valid signatures, so you can deploy the new one before the old stops working.
At-least-once
The only delivery guarantee a webhook sender can honestly make, which is why receivers must dedupe
Source: Flock webhook delivery contract
Push and pull do different jobs
A webhook answers "what just changed". It does not answer "what did I miss while my consumer was down", and it does not answer "what did this look like last quarter". Restatements make this concrete: a corrected filing is a new event, but reconciling your copy against the corrected history is a read operation. So the normal shape is push for freshness plus a read API for backfill and audit, which is what 13F API and shareholding pattern API cover on the pull side.
One caution specific to filing data. A webhook makes data arrive faster, not sooner than the filing itself. A 13F reports positions as of quarter-end and can be filed up to 45 days later, so a real-time push of a 13F event is real-time notice of a stale disclosure. The event time and the as-of date are different fields and should stay different in your systems.
What Flock's webhook surface does
Flock's Business plan includes signed webhooks alongside the REST API, at ₹39,999 per month, with annual billing at ₹3,49,999 and an included allowance of 100,000 requests per month. The published SLA is 99.5 percent.
The subscribable events today:
| Event | Fires when |
|---|---|
disclosure.created | A new disclosure row is recorded from ingestion |
convergence.created | A new multi-entity overlap is detected |
convergence.updated | An existing overlap is superseded or revised |
announcement.created | A new NSE or BSE company announcement is ingested |
Two further event types exist in the wire contract but are not emitted yet, and registration rejects them rather than accept a subscription that would stay silent.
Delivery mechanics:
- Signing.
x-flock-signature, HMAC-SHA-256 over the timestamp and the raw body, in the formt=<unix>,v1=<hex>, with a 300 second timestamp tolerance and constant-time comparison. Secrets carry awhsec_prefix. - Rotation. A rotate call returns the new secret once, and for 24 hours deliveries are signed with
both secrets, sending two
v1values, so there is no gap during deploy. - Headers for the receiver.
x-flock-event-id,x-flock-event-typeandx-flock-delivery-idaccompany each request. Delivery is at-least-once, so dedupe on the event id. - Envelope. A versioned JSON envelope with
id,type,api_version,occurred_atanddata. - Retries. Exponential backoff with dead-lettering after 10 attempts, roughly a day, plus a circuit breaker that disables an endpoint that keeps failing and an explicit re-enable call.
- Endpoint management. Register, list, get and deactivate endpoints, plus verify ownership, send a test event, rotate the secret and re-enable.
One editorial rule is enforced in the pipeline rather than left to the receiver. A disclosure.created
event only fires for attributions at the public confidence gate, so a quarantined or low-confidence
entity match is never pushed to a customer who may re-broadcast it. Convergence explanations pass the
compliance gate before they are persisted.
Access starts with a conversation rather than a self-serve signup. Details, including the fact that invoices currently carry no GSTIN because Flock is not GST-registered, are on the business page.
The honest limitation
A filing webhook API cannot make a disclosure arrive earlier than the filer files it, and it cannot give you exactly-once delivery. What it can do is remove polling latency, carry a signature you can verify, and expose its own failure states so a missed event is visible rather than assumed. Everything it pushes is a public regulatory disclosure with a source and a date attached. For the browsing equivalent, see stock filing alerts India, and for the underlying overlap signal, smart money convergence. Flock reports public filings with every claim sourced and dated. What any of it means for your money is your call to make.
Frequently asked questions
What is a filing webhook API?
It is an interface that pushes an HTTP request to a URL you own each time a new regulatory disclosure is recorded, instead of requiring you to poll an endpoint. The payload carries the event type, a stable event id and the disclosure data.
How do you verify a webhook came from the sender?
By recomputing an HMAC over the raw request body with a shared secret and comparing it to the signature header in constant time. Flock signs with HMAC-SHA-256 over the timestamp and raw body, sent as x-flock-signature in the form t=unix,v1=hex.
Why does at-least-once delivery matter?
Because a receiver can be sent the same event twice after a timeout or a retry. A sender that promises exactly-once is overpromising, so the correct design is a stable event id on every delivery and deduplication on the receiver side.
Should a webhook replace a filings API?
No. Webhooks tell you something changed and carry the payload for that change. Backfills, restatements and history still need a read API, so most systems use push for freshness and pull for reconciliation.
Flock tracks these filings, sourced, dated, and linked back to the original. See what smart-money entities disclosed, without the guesswork about what it means.
Disclosures shown are public regulatory filings. Data may be delayed or incomplete. Smart-money entities may no longer hold positions shown. Not investment advice.