Events

Events are the triggers that cause a webhook delivery. Event names are hierarchical: a parent topic (file) groups its child events (file.deduction.ready, file.validation.success, ...), and you can subscribe at either level.

How matching works

A published event is delivered to your subscriptions that match it:

• Exact match — a subscription on file.deduction.ready receives file.deduction.ready events.
• Parent match — a subscription on a parent prefix receives everything under it: a subscription on file receives file.deduction.ready, file.validation.failed, and any other file.* event.
• The hierarchy flows downward only: subscribing to a child (file.deduction.ready) does not deliver parent or sibling events.
• If the same targetUrl would be matched more than once for one event (e.g. via parent and child subscriptions), it receives a single delivery.

Choose your granularity:

{ "events": ["file"] }                    // everything in the file lifecycle
{ "events": ["file.deduction.ready"] }    // only deduction-ready notifications

Available events

Every import outcome produces a notification. Files that fail before processing even starts (e.g. transfer or format issues) also trigger file.processing.error — you never need to poll to discover that an import silently died.

Delivered payload shape

Every delivery has exactly two top-level fields — the event field always carries the specific event that happened, even when matched through a parent subscription:

{
  "event": "file.validation.failed",
  "data": {
    "fileName": "census_2026_05.csv",
    "message": "The file does not adhere to the required template.",
    "errors": [
      { "propertyName": "hireDate", "errorMessage": "Invalid date format." }
    ]
  }
}

For the complete walkthrough (signature validation, download, sandbox testing), see Receiving the Deduction File.