SEC filing webhook quickstart for developers

Use this guide to inspect SEC filing monitor notifications, test delivery into local code, and prepare the production handler before a formal monitoring plan goes live.

Short answer: A SEC filing webhook endpoint is a URL that receives structured POST notifications when a monitored filing or disclosure state changes. For evaluation, use webhook.site for request inspection, ngrok for localhost testing, or Pipedream for a hosted request bin or workflow. In production, respond with 2xx quickly, deduplicate by transition ID, verify signatures when enabled, and process slower work asynchronously.

Why webhooks?

CMD+RVL outcomes can deliver state changes by email, Slack, or webhook. Webhooks are useful when a filing monitor needs to feed a queue, internal review app, data store, or agent workflow.

When you evaluate an outcome, choose webhook delivery if your team wants machine-readable events rather than a human-only notification.

Webhook delivery is useful for developers because it supports:

• Request inspection: see headers, body, status, and delivery timing.
• Local testing: route a public URL to a server on your laptop.
• Structured handling: parse JSON payloads into a database, queue, or workflow.
• Evidence handoff: keep source and review links with the event when the outcome includes them.

This guide covers three practical paths: inspection with webhook.site, localhost delivery with ngrok, and hosted workflow testing with Pipedream.

---

Option 1: webhook.site for inspection

webhook.site gives you a unique URL instantly, with no signup required.

Steps

1. Go to webhook.site.

   The page shows a unique URL like:

   https://webhook.site/abc12345-6789-def0-1234-567890abcdef

2. Copy the webhook URL.

3. Use it in the outcome evaluation.

   During discovery, ask for webhook delivery and provide the webhook.site URL.

4. Watch the requests arrive.

   When a state change is delivered, inspect the POST request body, headers, query parameters, status, and timing.

Tradeoffs

• Fastest way to inspect a payload.
• Useful for a first delivery test.
• Temporary URLs are not a production endpoint.
• It does not run your local code.

---

Option 2: ngrok for localhost delivery

If you want transitions delivered directly to code running on your machine, use ngrok.

Steps

1. Install ngrok.

   On macOS, install ngrok with Homebrew. You can also download the agent from ngrok.com/download.

   brew install ngrok

2. Sign up for an account.

   Go to ngrok.com, create an account, and copy your authtoken from the dashboard.

3. Authenticate the agent.

   ngrok config add-authtoken YOUR_AUTH_TOKEN

4. Create a webhook receiver.

   Use this prompt with Claude or another coding assistant:

   I am setting up a webhook receiver to get state transition notifications from CMD+RVL outcomes. Help me create a simple webhook server that:
   
   1. Listens for POST requests on /webhook
   2. Parses the incoming JSON payload
   3. Logs the transition details: type, entity, and timestamp
   4. Returns a 200 OK response quickly
   5. Optionally stores transitions in a local file or database for later review
   
   I want to use Python, Node.js, or Go. Keep it simple and dev-friendly. Include instructions for running it locally and exposing it via ngrok.

5. Expose your local server.

   ngrok http 5000

   ngrok displays a public URL like:

   Forwarding  https://a1b2c3d4.ngrok.app -> http://localhost:5000

6. Use the ngrok URL in your evaluation.

   When authorizing an outcome, select webhook delivery and enter the ngrok URL with the /webhook path.

Now every transition will POST directly to your local server.

Tradeoffs

• Best option when you need to test your handler code.
• Lets you debug local logs, breakpoints, and database writes.
• Requires account setup and an agent process running locally.
• Use a stable domain or your own production endpoint before relying on it operationally.

---

Option 3: Pipedream for hosted workflow testing

RequestBin by Pipedream offers hosted webhook inspection and can route events into Pipedream workflows.

Steps

1. Go to pipedream.com/requestbin
2. Create a RequestBin
3. Copy the generated URL
4. Use it as the webhook destination
5. Add a Pipedream workflow step if you want to transform, store, or forward the event

Tradeoffs

• Useful when you want hosted inspection plus workflow automation.
• Good for quick transformations, alerts, or enrichment during evaluation.
• It is not the same as running your local handler. Use ngrok when the event must hit localhost.

---

Handling webhooks in production

For evaluation, the options above are enough. For production, use a stable endpoint owned by your team and implement these controls:

1. Idempotency: use transition_id or the outcome-specific event ID to deduplicate.
2. Signature verification: verify signatures when they are enabled for your monitoring plan.
3. Fast acknowledgment: return 2xx quickly and process slower work asynchronously.
4. Retry handling: expect retries after 5xx, timeouts, or transient network failures.
5. Observability: log receipt time, processing status, and downstream errors.

Production webhook setup is finalized when the evaluation moves into a formal monitoring plan.

Expected notification shape

Exact payloads depend on the outcome scope, but a useful filing notification should preserve:

• event type,
• monitored entity,
• filing or source reference,
• event timestamp,
• delivery timestamp,
• prior state,
• current state,
• evidence or review link when included.

Store the raw event first. Parse normalized fields after receipt so the original delivery remains available for review.

Common questions

What is a SEC filing webhook?

A SEC filing webhook is a URL that receives structured POST notifications when a monitored filing or disclosure state changes. It lets a developer inspect the event, store it, and route it into internal tools.

Which webhook testing tool should I use first?

Use webhook.site when you only need request inspection, ngrok when you need the event to reach a server running on localhost, and Pipedream when you want a hosted request bin or workflow step.

How should a production webhook handle retries?

Return a 2xx response quickly, deduplicate events by a stable transition identifier, verify signatures when enabled, and move slower work into an asynchronous job or queue.

What fields should a filing notification preserve?

A useful notification should preserve the event type, monitored entity, filing or source reference, event timestamp, delivery timestamp, prior state, current state, and any evidence or review link included for the outcome.

---

Next steps

1. Book discovery: choose an outcome and ask for webhook delivery.
2. Inspect your first transition: watch it arrive at your webhook endpoint.
3. Parse and process: build the handler logic.
4. Review with us: after the evaluation window, review delivery behavior and production requirements.

---

Related resources

• Developer hub - developer tools and resources
• SEC EDGAR MCP server - agent-ready filing metadata for Claude, Codex, and MCP clients
• SEC filing monitor - example outcome with webhook delivery
• Evidence Packs - how CMD+RVL keeps source context with delivered outcomes