Webhooks

After creating a new report request that includes a webhook_config.url, a report notification will be received via webhook. Once acompleted status is generated, access the file via the provided SFTP file_path.

The following details are provided in the webhook:

Field	Example	Description
`id`	`ae5821ad-4ca1-42a4-a2af-8bc46ed48f6b`	The unique identifier (UUID) of the settlement report. This `id` can be used in the Show Report API
`status`	`completed`	Status of the current report generation request. Values: `completed`, `failed`
`file_path`	`/normalised-file-storage/bose/settlement_report_v1.0.0_ae5821ad-4ca1-42a4-a2af-8bc46ed48f6b.cs`	Path of the file inside the SFTP folder. Note: This is not a clickable link and should be used programmatically
`schema_version`	`v1.0.0`	Version of the normalized field schema. This field is only present in files with a status of `completed`
`message`	`Report generated successfully and uploaded to SFTP. Please check the specified path.`	Descriptive message for a successful or failed report
`generated_at`/`failed_at`	`2026-01-06T11:57:26Z`	`generated_at`: Time of the completed report `failed_at`: Time the report failed to generate
`details`	`date_range`, `psps_without_files`, `psps_with_files`, `psps_checked`	`date_range:` The date range specified in the filter config `psps_without_files`: All PSPs checked via SFTP that do not have any files containing data within the specified date range `psps_with_files`: All PSPs checked via SFTP with files containing data within the specified date range `psps_checked`: All PSPs that were checked via SFTP for files containing data within the specified date range
`error_summary`	`error_count`, `error_code`, `psp_name`	`error_count`: The number of files in which duplicate columns were found. This value is typically 1, as the report generation process stops immediately upon detecting a duplicate column `error_code`: The error code returned when a duplicate column is detected. Values: -`DUPLICATE_COLUMN`: A duplicate column was detected in the file -`FILE_NOT_FOUND`: No files were found on the SFTP server for the specified date range `psp_name`: The name of the PSP in which the duplicate column was found

Additional details for status field:

Status	Message	Description
`completed`	“Report generated successfully and uploaded to SFTP. Please check the specified path”	The report has been successfully generated and is available via the SFTP `file_path`.
`failed`	“No settlement files found for specified date range and PSPs” "Report not generated - no data matched the specified filters" “DUPLICATE_COLUMN: Duplicate column headers detected: payer_country”	The report generation process encountered a fatal error and could not be completed. Some examples include duplicate columns existing within the raw PSP file, if no source file is found matching the filters configured in the API request (e.g., PSP name, date range), or if no data matches the filters specified in the request (e.g., country, payment method).

Status

Message

Description

completed

“Report generated successfully and uploaded to SFTP. Please check the specified path”

The report has been successfully generated and is available via the SFTP file_path.

failed

“No settlement files found for specified date range and PSPs”

"Report not generated - no data matched the specified filters"

“DUPLICATE_COLUMN: Duplicate column headers detected: payer_country”

The report generation process encountered a fatal error and could not be completed. Some examples include duplicate columns existing within the raw PSP file, if no source file is found matching the filters configured in the API request (e.g., PSP name, date range), or if no data matches the filters specified in the request (e.g., country, payment method).