Webhooks

Webhooks in DayZero go both ways:

• Outbound webhooks let you register an HTTPS URL and receive signed events when Order-to-Cash records change (orders countersigned, invoices sent, payments received), when month-end close inputs arrive, and, for partner credit programs, for every credit.* event. This is the part you integrate with.
• Inbound webhooks are how Stripe, Shopify, Plaid, Square and Ramp notify DayZero. They are set up automatically when you connect an integration; nothing to configure.

Outbound Webhooks

Register an endpoint

curl -X POST "https://api.ondayzero.com/api/v1/webhooks/o2c" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/dayzero",
    "event_types": ["order.countersigned", "invoice.sent", "payment.received"]
  }'

The response includes the plaintext secret exactly once — store it; later reads never return it (rotate it instead, see Test and manage). Supply your own secret (32–255 characters) if you prefer. url must be HTTPS and resolve to a public address (private, internal and cloud-metadata addresses are refused with 400). event_types is required, and a type that is neither listed below nor a credit.* event is refused with 400 (CREDIT_101) naming it. is_active: false registers an endpoint without delivering to it yet.

Event types

Every payload is a flat JSON object whose event field names the type. Amounts are in cents.

Partner credit events (credit.loan.originated, credit.payment.recorded, and the rest of the credit.* family) can be subscribed to on the same endpoints. They use their own envelope (id, sequence_no, type, occurred_at, credit_line_id, program_id, data) and are documented in Partner Credit Lines.

Month-end close events

These five tell a close agent that data is in, so it starts then instead of on a clock. They are not credit events: a credit-scoped API token cannot subscribe to them.

{
  "event": "plaid.sync.completed",
  "ledger_id": "0198a2c4-6e0b-7d3a-9a51-3f6f0c1d2e77",
  "ledger_name": "Chase Checking 1234",
  "plaid_item_id": "0198a2c4-1111-7d3a-9a51-3f6f0c1d2e11",
  "added": 42,
  "modified": 3,
  "removed": 1,
  "pending": 5,
  "posted": 40,
  "window_start": "2026-10-01T09:00:00+00:00",
  "window_end": "2026-10-01T09:00:12+00:00",
  "completed_at": "2026-10-01T09:00:12+00:00"
}

For a period or a payout the delivery id (X-DayZero-Delivery-Id) is period:{period_id}:created or payout:{stripe_payout_id}:landed, the same however many times the event is noticed, and DayZero records it once. An anomaly's delivery id is its fingerprint.

Close events

These nine keep a close dashboard up to date while a month is being closed. Like the events above they are not credit events. Each payload also carries business_id and emitted_at (ISO timestamp, UTC), so one receiver can serve many businesses. Dates are ISO YYYY-MM-DD; period_start is the first day of the month being closed.

Business days follow the Federal Reserve bank-holiday calendar: Monday to Friday, less New Year's Day, Martin Luther King Jr. Day, Washington's Birthday, Memorial Day, Juneteenth, Independence Day, Labor Day, Columbus Day, Veterans Day, Thanksgiving and Christmas. A holiday on a Sunday is observed the Monday after; one on a Saturday is not observed.

The events sent once have a stable delivery id: close-window:{period_start}:opened, close-step:{period_start}:{job_id}:{date}:overdue, pending-change:{pending_change_id}:decided, approval-round:{round_id}:decided, document-request:{document_request_id}:fulfilled and clarification:{clarification_id}:answered (an id longer than 64 characters is shortened with a hash). Every close.progress has its own.

close.window_opened is sent on the business day set in the business's agent_close_business_day (1 to 23, or -1 for the last business day of the month; empty means it is not sent). Set it with PATCH /api/v1/accounting-periods/settings or the update_accounting_period_settings tool. A month with fewer business days than that opens on its last one.

{
  "event": "pending_change.decided",
  "business_id": "0198a2c4-0000-7d3a-9a51-3f6f0c1d2e00",
  "emitted_at": "2026-10-06T14:02:11.418203+00:00",
  "pending_change_id": "0198a2c4-2222-7d3a-9a51-3f6f0c1d2e22",
  "tool_name": "categorize_transaction",
  "status": "applied",
  "round_id": null,
  "decided_by": "pat@example.com",
  "note": "Looks right"
}

What a delivery looks like

Each delivery is a POST to your URL. The body is the event's payload, exactly as listed above: one flat JSON object whose event field names the type — there is no wrapper around it (a credit event uses the credit envelope instead, see Partner Credit Lines). The headers are:

Verify deliveries

import hashlib
import hmac
import time


TOLERANCE_SECONDS = 300


def verify(secret: str, headers, raw_body: bytes) -> bool:
    timestamp = headers["X-DayZero-Timestamp"]
    if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    expected = (
        "v1="
        + hmac.new(
            secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
        ).hexdigest()
    )
    candidates = [
        headers.get("X-DayZero-Signature"),
        headers.get("X-DayZero-Signature-Previous"),
    ]
    return any(c and hmac.compare_digest(c, expected) for c in candidates)

Compute the HMAC over the bytes exactly as received — re-serialising the JSON will change the digest. The timestamp is inside the signature, so refuse one more than five minutes from your clock; a captured request cannot be replayed with a fresh timestamp. Each retry is signed again with a new timestamp. Respond with any 2xx at once to acknowledge, and do the work after: an attempt has 15 seconds in all, from looking up your host to the first 1 KB of your answer, and one that runs past it is stopped and counted as a failed attempt. Only that first 1 KB of the answer is read. DayZero never follows redirects, so a 3xx counts as a failure.

Retries and delivery history

A delivery is sent once the operation that produced the event has been saved, normally within a second, so the record it describes can always be fetched when your endpoint is called; an operation that fails and is rolled back sends nothing. Until its first attempt a delivery is pending, and every minute any delivery still pending ten seconds after it was written is sent. While an attempt is being made the delivery is sending; nothing else sends it meanwhile, and an attempt DayZero could not finish (it stopped mid-send) is counted as failed two minutes on and retried on the schedule below. A slow endpoint does not hold up other endpoints' deliveries.

A non-2xx response or a network failure marks the delivery retrying and re-sends it with exponential backoff — after 1 minute, 5 minutes, 30 minutes, 2 hours, then 8 hours. After six attempts in total it becomes failed. Retries carry the same body, the same X-DayZero-Delivery-Id and a fresh timestamp and signature, so make your handler idempotent (key on the delivery id or the record IDs in the payload). Deactivating or deleting the endpoint gives up its queued retries (the delivery becomes failed).

curl "https://api.ondayzero.com/api/v1/webhooks/o2c/ENDPOINT_UUID/deliveries?status=failed&limit=50" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"

Deliveries are listed oldest first. Filter with status, event_type and since (a timestamp; deliveries recorded at or after it). Each delivery reports event_type, status (pending, sending, succeeded, retrying, failed, or no_subscribers when an event fired while no active endpoint subscribed to it and nothing was sent), attempts, the last response_code, the first 1 KB of response_body, error, latency_ms, delivery_key (the X-DayZero-Delivery-Id value) and next_retry_at while an attempt is queued. The list is cursor paginated with cursor and limit (default 50, maximum 100).

POST /api/v1/webhooks/o2c/{endpoint_id}/deliveries/{delivery_id}/redeliver sends a delivery again during the call, as a new delivery linked to the original by redelivery_of, and returns it with the attempt's outcome: status (succeeded, or retrying with the receiver's response_code or the error), response_code and attempts. An original still waiting to be sent or retried is stopped and marked failed; one being sent at that moment is refused with 409 (CREDIT_646) until its attempt has finished.

Test and manage

# Send a synthetic event to this one endpoint only (it must be active)
curl -X POST "https://api.ondayzero.com/api/v1/webhooks/o2c/ENDPOINT_UUID/test-fire?event_type=invoice.sent" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"

Test payloads look like {"event": "invoice.sent", "test": true, "emitted_at": "...", "business_id": "..."} and are signed like real ones. No other endpoint on the business receives a test, so endpoints_notified is always 1. The attempt is made during the call, so the response also carries its status, response_code and the delivery_id to look up. A credit event type is sent in the credit envelope instead (see Partner Credit Lines). GET /api/v1/webhooks/o2c lists endpoints (cursor paginated, limit default 50, maximum 100), GET /api/v1/webhooks/o2c/{endpoint_id} fetches one, and DELETE /api/v1/webhooks/o2c/{endpoint_id} removes it along with its delivery history.

PATCH /api/v1/webhooks/o2c/{endpoint_id} changes url, replaces event_types (at least one) or sets is_active; omitted fields stay as they are. Deactivating stops deliveries and gives up queued retries.

# Mint a new secret (returned once). The old secret keeps signing for overlap_minutes
curl -X POST "https://api.ondayzero.com/api/v1/webhooks/o2c/ENDPOINT_UUID/rotate-secret" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{"overlap_minutes": 30}'

overlap_minutes is 0–60 (default 60). While the overlap runs, each delivery also carries X-DayZero-Signature-Previous, so you can deploy the new secret without dropping events; 0 retires the old secret at once. previous_secret_expires_at on the endpoint shows when the overlap ends.

Webhook emission is best-effort: a failing receiver never blocks the underlying business operation, so treat webhooks as a nudge and the REST API as the source of truth.

Inbound Webhooks (integrations)

DayZero receives event notifications from connected services at /api/v1/webhooks/{provider}. These endpoints take no Bearer token — each request is authenticated by the provider's own signature scheme — and they are not something API consumers call.

Processing follows the same pattern for each: verify the signature (Stripe's Stripe-Signature, Shopify's X-Shopify-Hmac-Sha256, Square's x-square-hmacsha256-signature, Ramp's per-subscription signing secret, Plaid's Plaid-Verification JWT), store the event, then update records or nudge the relevant summary posting. Per-sale events are deliberately not posted one journal entry at a time — the ledger only sees daily or per-payout summaries.

Common errors