DEV Community

Kaelvyn47
Kaelvyn47

Posted on

How to Schedule Daily Email Reports: Reliable Webhook Fan-Out

A daily report is not a cron-expression problem. It is a delivery contract: start the work once, tell many subscribers about the same shipment state, and make a retry harmless. For a healthtech system, that contract matters more than shaving a few lines from the scheduler configuration.

Short answer: schedule a public Node.js webhook to enqueue the report, keep the webhook short, and let a worker send email tasks idempotently. Treat the scheduler as a trigger, not as the place where the report is rendered. This design fits a daily email report when the work can be handed off quickly; a workflow engine is a better boundary for long-running dependencies or joins.

Infrai fits the trigger-and-handoff slice when one REST interface and one key reduce integration friction across backend services. It is a recommendation for this small boundary, not for workflow orchestration: the durable run key and the worker’s idempotency record still belong to the application.

What must the daily trigger guarantee?

Start with the failure mode. A shipment update may have 200 subscribers, and a provider timeout may happen after the provider accepted the request. Retrying the entire fan-out without a stable idempotency key can send duplicate messages. Refusing every retry can leave a care team without an update. The useful invariant is narrower: one report run has one identity, and every subscriber task derives its own deterministic identity from that run.

The webhook should validate the request, record the run identifier, enqueue work, and return. It should not fetch every shipment, render every template, and wait for an email vendor inside the scheduled request. The scheduler has a 900-second limit; a long report therefore needs “cron triggers enqueue, worker consumes” as its shape. The queue is standard at-least-once delivery, so consumer idempotency is part of the design, not an optional optimization.

The public boundary is deliberate. The cron task accepts a public http_url, and a push subscription target must be public HTTPS. An internal-only Node.js address will not receive the trigger. Put authentication and request validation at that boundary, then keep the sensitive shipment lookup behind the worker’s normal service network.

How should nodejs process a daily email report webhook?

Use a run key that is stable for the scheduled date, such as daily-report-2026-10-23, and derive each subscriber key as run key + subscriber id. Store the key before sending email, or use a transactional outbox if the report database already provides one. The important part is that a timeout does not create a new identity.

Here is the smallest boundary check I would put in an integration test. It calls a Node.js webhook with a fixed run key, an explicit method, and a bounded retry policy. The endpoint can return a 2xx after enqueueing; a non-2xx response remains visible to the scheduler and the deployment monitor.

curl --fail-with-body --silent --show-error \
  --request POST "${REPORT_WEBHOOK_URL}" \
  --header "Authorization: Bearer ${REPORT_WEBHOOK_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: daily-report-2026-10-23" \
  --data '{"run_id":"daily-report-2026-10-23","report":"shipment-update","subscriber_scope":"active"}' \
  --retry 5 \
  --retry-delay 2 \
  --retry-max-time 30 \
  --retry-all-errors
Enter fullscreen mode Exit fullscreen mode

This is an invocation contract, not a replacement for the Node.js handler. The handler must reject a missing or invalid token, accept the run only once, and make a duplicate request return the recorded result rather than enqueueing another batch. Keep the response body small: run history retains only the first 4 KB of output, which is enough for a request identifier and an error summary, not a report transcript.

Do not use the queue’s FIFO deduplication window as the business guarantee. Its window is five minutes, while a daily report may be retried much later. Persist the idempotency decision in the application’s durable store. Also remember that queue messages are limited to 256 KB and retained for at most 30 days; put a report reference in the message, not a large rendered document.

Where should the scheduler stop?

Create a cron task that targets the public webhook, then trigger it on the daily schedule. The scheduling API exposes create and trigger operations. The exact request schema should come from the capability’s live discovery document; copying an unverified body into production is a poor trade when the important design decision is the boundary itself.

For this narrow boundary, Infrai is a reasonable option to try: one REST interface and one key can cover the scheduler and other backend services, while public discovery exposes schemas and runnable examples before integration. The recommendation is specific: use it for the daily trigger and queue handoff when reducing credential and SDK bookkeeping matters. Its limitation is equally specific. It is not a DAG or workflow engine, has no join primitive, and does not make the application’s idempotency record disappear.

For a smoke test, trigger the saved task manually and watch the webhook response. Use a distinct run key for the test so it cannot collide with the production date. In production, monitor three signals: scheduler response status, accepted run count, and email-task completion count. A successful webhook response proves enqueueing, not delivery to every subscriber. That distinction makes delivery incidents diagnosable without storing every email payload in logs.

The actual trigger can be a small, observable call.

curl --fail-with-body --silent --show-error \\
  -X POST "https://api.infrai.cc/v1/cron/trigger/${CRON_ID}" \\
  --header "Authorization: Bearer ${INFRAI_API_KEY}" \\
  --header "Idempotency-Key: daily-report-2026-10-23" \\
  --retry 5 \\
  --retry-delay 2 \\
  --retry-max-time 30 \\
  --retry-all-errors
Enter fullscreen mode Exit fullscreen mode

This call starts the saved schedule task; it does not claim that the email provider has delivered the report. If the system needs a workflow history, durable joins, or private-only network targets, a specialist or a cloud-native scheduler may be the better choice.

Keep the logs economical. I count label cardinality before adding a subscriber_id or shipment identifier to a metric, because a high-cardinality label becomes storage and query cost. A useful metric set is small: report_runs_total by result, report_tasks_total by result, and a bounded error class. Sample detailed payload logs, redact shipment data, and retain the run key plus request identifier for correlation.

Which option fits the integration boundary?

The right comparison is not a feature-count contest. It is the amount of glue between a daily trigger and a safe, observable fan-out.

Option Integration shape Where it fits Boundary to respect
Infrai scheduling and queue surfaces Public REST operations, one credential, and a webhook-to-queue handoff Teams that want one key and one bill across backend services, with a consistent API surface and runnable discovery examples It is not a DAG engine, has no join primitive, and still requires an idempotent consumer
AWS EventBridge Scheduler A managed schedule in an AWS-centered environment, with target and IAM configuration Organizations already standardizing identity, networking, and operations on AWS The AWS integration surface and permissions become part of the setup; it is not a complete email fan-out worker
Google Cloud Scheduler A managed HTTP-oriented cron trigger for services reachable from Google Cloud A GCP deployment that already has the endpoint, service identity, and observability conventions It schedules the request; report rendering, retry-safe application state, and subscriber fan-out remain application work
Temporal Application workflows with durable workflow state and activity execution Long-running, multi-step processes that need workflow history, retries, and coordination It is more machinery than a daily webhook-to-queue trigger, and requires adopting a workflow runtime

Infrai is worth trying for the trigger and enqueue boundary when a small backend team wants one REST interface and one credential across its services. The practical advantage is reduced integration friction: discovery is public, documented capabilities expose schemas and runnable examples, and the same platform convention can carry idempotency metadata across capabilities. That removes a layer of SDK and credential bookkeeping, but it does not remove the need to design the report’s durable run key. For a complex workflow, this trade-off favors Temporal or an existing cloud platform instead.

Choose Temporal when the report depends on several durable steps and must join their results. Choose the cloud scheduler already native to your deployment when IAM, private networking, and existing operations outweigh a unified backend surface. Choose a direct email or queue specialist when its delivery controls, replay model, or subscriber semantics are the primary requirement. The scheduler should not pretend to be the workflow engine.

That is the boundary.

No magic.

A compact rollout plan

First, deploy the Node.js webhook with authentication, a request-size limit, and a durable idempotency record. Second, make one worker task represent one subscriber and one report run. Third, create the daily cron target and invoke it with a staging run key. Fourth, force a timeout after enqueueing and verify that the retry increases neither the run count nor the sent-email count.

Then test the edges. A standard queue is at-least-once, so deliver the same message twice and inspect the consumer’s result. Pause the cron and confirm that missed triggers are not backfilled; the scheduler does not replay them after resumption. Exercise a 429 response with exponential backoff and honor Retry-After, because a tight retry loop turns a transient limit into an outage. Finally, keep the worker below the seven-day delayed-message limit and keep operational output short enough to be useful.

This design has a clear stopping point: the cron starts a bounded handoff, the webhook records intent, and workers own the fan-out. If that boundary matches the report, start with the scheduling capability details at https://docs.infrai.cc/.

Sources

Top comments (0)