A webhook report notification is an HTTP request that one system sends to another the moment a report event happens, most often when a report finishes running or fails. Instead of someone checking a folder or an inbox, your endpoint is told about it. To make it reliable, you need five things: an HTTPS endpoint, a compact payload that identifies the report, a signature check, duplicate handling and delivery monitoring.
This guide covers each of them with concrete examples from public documentation, then shows where webhooks fit next to scheduled report delivery for Power BI, SSRS, Tableau and Crystal Reports.
TL;DR
- A webhook is an event-driven HTTP POST. For reports, the useful events are "report completed" and "report failed".
- Keep the payload small: report ID, status, timestamp and a link to fetch the file, not the file itself.
- Verify an HMAC-SHA256 signature on the raw body, require HTTPS, and deduplicate by event ID.
- Expect retries. Return a 2xx quickly, process asynchronously, and log every attempt.
- Webhooks announce that a report is ready. A scheduler and delivery engine still has to build, format and send it.
Table of Contents
- What webhook report notifications are
- What a good report webhook payload contains
- Setting up the endpoint
- Securing webhook report notifications
- Retries, duplicates and failed deliveries
- Monitoring whether notifications arrived
- Webhooks versus scheduled delivery
- Using this with Power BI, SSRS, Tableau and Crystal Reports
- Our perspective
- Automating the report side with ChristianSteven
- FAQ
- Sources
What webhook report notifications are
A webhook is an HTTP request triggered by an event in a source system and sent to a destination system. LuxSci describes webhooks as pushing information as events happen, so customers do not have to pull from its API. Applied to reporting, the source system is whatever generates or schedules your report, and the destination is a URL you control.
Mode's webhooks are a clear example. Other applications subscribe to events in a workspace, including when a report finishes running. Mode sends a POST to a URL you choose in real time, and the payload carries the event name and a link to the related API endpoint.
That last detail matters. The notification is a signal with a pointer, and the receiver decides what to do next: fetch the file, post to a chat channel, update a ticket, start a downstream load or alert someone that a run failed.
Webhook, email alert or polling?
| Approach | How you learn a report is ready | Best for | Weak spot |
|---|---|---|---|
| Webhook | The source calls your URL on the event | Triggering another system immediately | You must run a reliable endpoint |
| Email notification | A person or mailbox receives a message | Human awareness | Hard to automate, easy to miss |
| Polling | Your code asks the API on a timer | Simple setups, firewalled receivers | Wasted calls and delay between checks |
Connectly's documentation puts the trade-off plainly: instead of polling the Reports API on a schedule, you register an endpoint that is called when a run completes. Its payload includes a signed URL to download the CSV without an extra API call.
What a good report webhook payload contains
The best payloads are compact. They identify the event, the report and the moment it happened, then point to where the content lives. Public documentation shows a consistent pattern.
- Hybiscus sends a JSON body with an event field set to report.completed or report.failed, a task ID and a URL to access the report.
- Obkio's example includes report ID, organization ID, name, timestamps, date range, status, user, timezone, attempt count, download URL, filename and size.
- Y2 uses CloudEvents 1.0 and identifies the report with its ID, status, generation time, subscription ID and API links rather than embedding the full report.
- AutoReport goes the other way and ships content in the body, including markdown and HTML, plus metrics, schedule and destinations.
Fields we would insist on
- Event type, such as completed or failed, so one endpoint can route both outcomes.
- Unique event ID that stays the same across redeliveries. SolidGate's "Report generated" webhook carries an event ID for deduplication and an attempt number, which is a good model.
- Report identifier and name, so the receiver knows which report it is.
- Timestamps, both when the event occurred and when the report was generated.
- Status and failure reason when a run fails.
- A retrieval link with limited lifetime or authentication, instead of the file itself.
Why not embed the file? Large bodies hit payload limits and slow your endpoint's response, and sensitive data ends up in logs and queues. A pointer lets you apply access control at the moment of download.
Setting up the endpoint
The steps are similar whichever platform sends the event.
- Create a public HTTPS URL that accepts POST requests. Y2 requires HTTPS for report webhook deliveries, and Dashloom rejects URLs that target loopback, private, link-local or metadata hosts. Plan for a reachable address, not localhost.
- Register the URL as a destination in the sending system, with a shared secret if it supports one. Obkio's webhooks have a configurable URL and optional secrets.
- Send a test event. Y2 offers a test-webhook workflow before you assign the configuration to a delivery profile. Use it to confirm your endpoint parses the body and returns a 2xx.
- Attach the destination to a rule or schedule, so the right reports fire the right webhook.
- Acknowledge fast, work later. Validate the signature, put the event on a queue, return 200, and do the real work asynchronously.
Respect the timeout
Timeouts are short. Both dbt and AutoReport use a 10-second window. dbt warns that a response arriving after the timeout can be logged as a failure even if your server eventually answers successfully. That is how teams end up with phantom failures and duplicate runs.
Securing webhook report notifications
A report webhook is an unauthenticated door into your network unless you lock it. The OWASP Webhook Security Cheat Sheet recommends HTTPS with TLS 1.2 or higher, HMAC-SHA-256 signatures, timestamp tolerance, event-ID deduplication, secret storage and rotation, payload limits, rate limiting and asynchronous processing.
A practical checklist
- Verify the signature on the raw body. Y2 recommends HMAC-SHA256 over the exact raw body with a constant-time comparison. Parsing and re-serializing JSON first can change the bytes and break the check.
- Reject stale requests. AutoReport's signature covers the timestamp and body, which lets you enforce a replay window.
- Keep HTTPS even with signatures. OWASP notes that signatures authenticate and protect integrity but do not encrypt data, so sensitive report content still needs TLS.
- Protect the download step. Obkio lets you fetch a report either from a public URL or by using the secret to sign a request to a signed_download endpoint that returns a URL valid for 5 minutes. Short-lived links are a sound pattern for financial or HR reports.
- Store secrets outside code and rotate them on a schedule.
For reports with personal or financial data, send as little as possible in the notification and keep the content behind your own authentication.
Retries, duplicates and failed deliveries
Every serious webhook sender retries, which means every receiver sees duplicates eventually. Retry policies differ, so check the one you depend on.
| Sender | Attempts | Delay pattern |
|---|---|---|
| Y2 | 5 total | 5 seconds, 30 seconds, 5 minutes, 30 minutes; five consecutive failures pause the destination |
| dbt | 5 | Delivery logs kept for 7 days |
| AutoReport | Up to 5 retries | Over about 1 hour |
| Obkio | Up to 10 | Exponential, from 1 minute up to 1 hour |
| Hybiscus | Up to 8 | Exponential, 30 seconds to 64 minutes |
Y2 retries network errors, timeouts, HTTP 408, 429 and 5xx responses. That tells you which of your own responses should trigger a retry (a temporary failure) and which should not (a bad signature should return a 4xx).
Make handlers idempotent
Because retries can deliver duplicates, Twilio recommends storing processed message IDs or timestamps and returning success without repeating side effects when an event was already handled. For reports, that means a second "report completed" event must not send a second email to the CFO.
Dashloom takes this to the sender side: a report and channel pair has one delivery ledger entry, and retrying a delivered pair does nothing.
Don't rely on webhooks alone for critical reports
A webhook can still be lost if your endpoint is down longer than the retry window. For anything with a deadline, add a safety net: a periodic check for reports that have no matching receipt, or a failed-schedule query against the source system. Pair the push with a reconciliation pull.
Monitoring whether notifications arrived
You cannot fix what you cannot see. Hookdeck lists success rate, failure rate, attempts per event, response latency, queue depth, oldest pending event and scheduled retries as useful operational metrics. It also recommends tracing ingestion, routing, each delivery attempt with timestamp, status and latency, and the final state, so a missing notification can be diagnosed rather than guessed at.
A minimal setup:
- Log the event ID, report ID, attempt number and response code for every request.
- Alert when the oldest pending event passes a threshold you choose, such as the length of your reporting window.
- Review the sender's delivery log. dbt, for example, offers a Recent Deliveries view of successes and failures, but only keeps logs for seven days, so export what you need for audits.
Webhooks versus scheduled delivery
A webhook tells you something happened. It does not decide what the report contains, who gets which version, in what format, or where the file lands. That is the job of a scheduling and delivery layer.
The two work together in a few common patterns:
- Completion hook: a scheduled run finishes, and a webhook tells your pipeline to archive the PDF, update a status page or start a downstream job.
- Failure hook: a failed run notifies an on-call channel with the report name and reason, instead of someone discovering it from an angry email on Monday.
- Inbound trigger: an event in another system, such as a finished data load or a closed accounting period, calls an API that runs the report immediately rather than waiting for the clock.
- Digest: instead of one message per event, a summary of everything over a period. LuxSci can send a digest of events on a configurable interval, from every minute to once a day, only when there are new events.
If you want to learn more about the inbound trigger pattern, our guide on scheduling reports via API walks through it. For what happens when a destination rejects a delivery, see protocol-aware report delivery retries.
Using this with Power BI, SSRS, Tableau and Crystal Reports
None of these platforms was built around a general-purpose, outbound "report finished" webhook for every scenario, so teams usually combine native features with an automation layer. The pieces you need are an API to run and monitor schedules, and a way to react to events.
Our CRD documentation, for example, describes APIs for creating and executing schedules and checking failed schedules. That is the shape you want: your webhook receiver or workflow engine calls an API to run a report on an event, and a status query confirms outcomes. For Power BI and SSRS, see the PBRS report automation API, and for Tableau the ATRS report automation API.
If your environment is on-premises, the security model matters as much as the plumbing. We cover that in securing an on-premises report delivery API and in an REST API reporting checklist for enterprise IT.
Our perspective
Most of the webhook questions we hear are really delivery questions. A team wants to know when a report is ready, but what they need is for the right report to reach the right person, in the right format, on time, with a record that it did.
That is why we think of notification as one step in a chain. Event-driven triggers start a run when the business event happens, not when a clock says so. Data-driven bursting personalizes the output per recipient. Exports to PDF and Excel and delivery to email, cloud, database and collaboration destinations finish the job. Error handling and a REST API let your other systems start runs and check results.
Native subscriptions in a BI platform stop short of that once reporting demand grows, and custom scripts around them become something one person understands and everyone else fears. We built PBRS, ATRS and CRD so IT teams get an unattended, auditable process without maintaining that glue code.
If you build webhook receivers, treat them like any production service: sign, verify, deduplicate, log. Then let the report engine do what it is built to do.
Christian Ofori-Boateng
Automating the report side with ChristianSteven
If your goal is event-driven report delivery across Power BI, SSRS, Tableau or Crystal Reports, our products cover scheduling, personalization, export and delivery, with event triggers, data-driven schedules, a REST API and automated error handling. They run on premises, and we are SOC 2 Type II certified.
See PBRS, ATRS, CRD and IntelliFront BI and choose a subscription or perpetual license after a trial or demo. Pricing is not published, so request a quote from the product page.
FAQ
What is a webhook report notification?
It is an HTTP POST sent to a URL you control when a report event occurs, usually completion or failure. The body identifies the event and the report and often links to the file. Your system then decides what to do, such as downloading it or alerting a team.
Should the webhook contain the report itself?
Usually not. A compact notification with a report ID, status, timestamp and a retrieval link keeps the request small and the data behind access control. Y2, Hybiscus and Connectly all follow a pointer pattern, while some tools embed content in the body.
How do I stop duplicate notifications from causing duplicate actions?
Store the unique event ID of every notification you process. If the same ID arrives again, return a 2xx and skip the work. Senders retry on timeouts and server errors, so duplicates are normal.
How do I know a webhook is genuine?
Verify the HMAC-SHA256 signature against the raw request body using your shared secret, and reject requests outside a short timestamp window. Require HTTPS as well, because a signature proves origin and integrity but does not encrypt the content.
Can I use webhooks with Power BI or Tableau reports?
Yes, typically through an automation layer or API. Your receiver or workflow calls an API to run a scheduled report on an event, and a status query checks the result. Check the API documentation for the product you use.
Sources
- Automated Reporting with Webhooks, LuxSci
- Webhooks, Mode Support
- Webhook Delivery, Y2
- Report Webhooks, Obkio Docs
- Webhooks for Reports, Hybiscus Docs
- Webhooks, AutoReport
- Report generated, SolidGate API docs
- Report Webhooks, Connectly Docs
- Automated reports and delivery, Dashloom Docs
- Webhooks for your jobs, dbt Developer Hub
- Webhook Security Cheat Sheet, OWASP
- Webhook security, Twilio
- Webhook Observability Architecture, Hookdeck
- CRD API documentation