Getting StartedWebhooks

Event Types

List of event types

Overview

This article provides a list of event types that can be subscribed to using webhooks. An event represents something that has happened in the system, e.g. file ingestion, etc.

For detailed description of how to configure webhooks for these event types, refer to Setup Webhook Subscription via API

Event Types

Approval Workflow Events

Event TypeWhen Sent
workflow.approval.pendingWorkflow enters PENDING state; an approver at the current level is expected to act.
workflow.approval.approvedAction submitted for approval succeeds.
workflow.approval.rejectedAn approver rejects at any level.
workflow.approval.cancelledRequestor cancels.
workflow.approval.invalidUnable to complete the approved action.

Data Fields

Data TypeDescription
IdentifiersrequestId, productArea, status.
Progresslevel and totalLevels (both 0 for auto-approve).
TimingtransitionTime: when the workflow moved into this state.
Usersrequestor, approver (null on pending), approverGroup (Fynapse user-group name), finalizedBy (username of the user who took the terminal decision, or system for auto-approve), requestorComment, approverComment.
Deep-linklink: an HTTPS URL to the approval list in pa-web filtered by requestId.
Errorson invalid only: errorSource (INVALID_CONFIGURATION when the config was invalid at request time, APPLICATION_OF_CONFIGURATION when downstream data application failed) and a list of errorMessages.

Ordering at the subscriber’s endpoint is best-effort, not guaranteed. Events for a given request are published in the correct order, but if one delivery gets stuck in retries while the next succeeds, the subscriber can receive them out of order. Subscribers should rely on the status field (and level for multi-level flows) rather than on receipt order.

  • Auto-approve workflows never emit pending. They emit approved when downstream data application succeeds, or invalid if it fails.
  • The approved status requires downstream success. Internal approval by the last approver is not sufficient; approved is only on DATA_APPLIED. If the downstream service returns DATA_FAILED, the workflow reverts straight from internally-approved to invalid, and subscribers see pending…pending → invalid with no approved in between.
  • The invalid status has two oaths:
    • Config-invalid path — sent at request time with no preceding event. errorSource = INVALID_CONFIGURATION.
    • Data-application-failed path — preceded by one or more pending events (but never by approved). errorSource = APPLICATION_OF_CONFIGURATION.
  • Multi-level approvals emit one pending per level before the terminal event.
  • The pending status events always have approver and approverComment = null.

Ingestion Events - ingestion.processing.succeeded and ingestion.processing.failed

When sent:

  • ingestion.processing.succeeded - an ingestion finished processing without errors.
  • ingestion.processing.failed - an ingestion finished processing in error.

The purpose of this event is to notify the receiving system that processing of a previously submitted ingestion produced a DONE or ERROR outcome.

The outcome may still be interim — use isFinal (see the field below) to tell whether it is definitive. The isFinal can be set to false, e.g.

  • for ingestion.processing.succeeded - if the ingestion file contained Unposted Journals that are awaiting their posting date. Then once the Journals are posted when their posting date arrives, isFinal will change to true.
  • for ingestion.processing.failed - if the ingestion file contained errors that are undergoing reprocessing. Then if the reprocessing is unsuccessful, isFinal will change to true.

Use these events to track processing without polling.

Data Fields

FieldTypeDescription
ingestionIdstring (UUID)Identifier of the ingestion, as returned when the data was submitted.
processingStatusstringDONE for success, ERROR for failure.
finishedOnstring (ISO-8601) | nullWhen processing finished.
isFinalbooleantrue if this is the definitive outcome. false is an interim result that may be followed by another notification for the same ingestionId (for example while downstream flows are still settling).

Example

{
  "event_id": "a3efc743-ac6c-463b-aa19-4dd9c45b5b96",
  "event_type": "ingestion.processing.succeeded",
  "metadata": {},
  "event_timestamp": "2026-03-18T12:00:01.234Z",
  "data": {
    "ingestionId": "5b8f0c0e-2b7a-4f1e-9c3d-0d6a1b2c3d4e",
    "processingStatus": "DONE",
    "finishedOn": "2026-03-18T12:00:00Z",
    "isFinal": true
  }
}

The failed variant has the same shape with event_type ingestion.processing.failed and processingStatus ERROR.

Extract Upload - extract.upload.completed Event

When sent: An extract file was uploaded to cloud storage and is ready to download.

The purpose of this event is to notify the receiving system that an extract configured to deliver to cloud storage has finished and the file has been written to the storage bucket. The file is available to download and process.

This event is emitted only for extracts with cloud storage as destination and only once the run has fully succeeded:

  • the extraction completed (extractionStatus COMPLETED)
  • the file was uploaded (uploadStatus SENT)
  • and — if the extract is configured to produce a manifest — the manifest has also been delivered.

When you receive this event the file (and its manifest, if any) is ready to download. Because of these conditions, the extractionStatus, uploadStatus and uploadSpace fields are constant for this event; they are listed in the table below for completeness.

Data Fields

FieldTypeDescription
extractLogIdstring (UUID)Identifier of the extract run.
rerunNumberintRerun counter for this run (0 for the first run).
extractNamestringName of the extract.
configurationNamestringName of the extract configuration.
extractConfigurationIdstring (UUID)Identifier of the extract configuration.
startedOnstring (ISO-8601) | nullWhen the run started.
uploadedOnstring (ISO-8601) | nullWhen the file was uploaded.
extractionStatusstringExtraction outcome. Always COMPLETED for this event.
uploadStatusstringUpload outcome. Always SENT for this event.
uploadSpacestringDestination of the file. Always CLOUD_STORAGE for this event.
executedstringHow the run was triggered: AUTOMATICALLY (scheduled) or MANUALLY.
generatedBystring | nullUser or process that triggered the run.

Example

{
  "event_id": "c1d2e3f4-5678-49ab-bcde-0123456789ab",
  "event_type": "extract.upload.completed",
  "metadata": {},
  "event_timestamp": "2026-04-14T09:54:45.040Z",
  "data": {
    "extractLogId": "7f3a9b2e-1d4c-4f8a-6b0e-3d7c9a1f4b2e",
    "rerunNumber": 0,
    "extractName": "Daily balances",
    "configurationName": "daily-balances",
    "extractConfigurationId": "2b7a4f1e-9c3d-0d6a-1b2c-3d4e5f60718e",
    "startedOn": "2026-04-14T09:54:43.674Z",
    "uploadedOn": "2026-04-14T09:54:44.900Z",
    "extractionStatus": "COMPLETED",
    "uploadStatus": "SENT",
    "uploadSpace": "CLOUD_STORAGE",
    "executed": "AUTOMATICALLY",
    "generatedBy": null
  }
}

Balance Extract - balance.extracted Event

Please note that in addition to steps 1-3 from Webhook Configuration Balance Extract Event requires a 4th step, adding an extract in the UI, described below.

Step 4 — Create a Balance Extract with Webhook Target

You will need Extractions Editor role assigned, e.g. Editor, to create the extract on the Extracts screen.

  • Go to Operations → Extracts → Extracts in Fynapse
  • Create a new extract
  • Set Target name to Webhook
  • Select Balances as the data source
  • Complete the configuration
  • Wait for schedule to Activate or run the extract manually

See Data Extraction for more details.

When the extract runs, balance.extracted events are generated and delivered to your webhook endpoint.

Event Format

The purpose of this event is to deliver a balance.extracted event to the receiving system.

Please note that the contents of the data property will be based off your selected Balance Query.

{
  "event_id": "a3efc743-ac6c-463b-aa19-4dd9c45b5b96",
  "event_type": "balance.extracted",
  "metadata": {
    "eventType": "balance.extracted",
    "startedOn": "2026-04-14T09:54:43.674940Z",
    "extractConfigurationName": "test"
  },
  "event_timestamp": "2026-04-14T09:54:45.040Z",
  "data": {
    "node": "Node1",
    "account": "222",
    "balance": 1.0,
    "productName": "",
    "transactionCurrency": "GBP"
  }
}