Programmatic Report Delivery via Webhook
Overview
Hyperswitch supports asynchronous report generation for automated workflows. You can trigger a report using an API key and receive the completed report through a webhook.
The webhook payload contains a pre-signed URL to download the CSV file. The CSV file is not included in the webhook payload.
Programmatic report delivery is supported only at the Merchant and Profile levels. Organization-level reports are not supported.
How It Works
Send a report request with a time range, email address and
returnUrl.Hyperswitch accepts the request and starts report generation.
Hyperswitch uploads the completed CSV file to secure storage.
Hyperswitch sends a signed webhook to your
returnUrl.Verify the signature and download the report using
data.download_url.
Report generation can take a few seconds or several minutes, depending on the amount of data.
Prerequisites
Before you begin, ensure that you have the following:
a Hyperswitch sandbox/production API key
at least one valid email address for the `emails` field
a public HTTPS endpoint that can receive
POSTrequestsyour Profile ID or when requesting a Profile-level report
Note: You do not need to provide a Merchant ID for Merchant-level reports. Hyperswitch identifies the Merchant from the API key.
Supported Report Types
You can generate the following reports:
Payments
payments
Refunds
refunds
Disputes
dispute
Payouts
payouts
Authentications
authentications
Note: Use
disputein the endpoint URL, notdisputes. Authentications is only supported in sandbox
Sandbox Endpoints
Merchant-Level Endpoints
Use these endpoints to generate a report for the Merchant associated with your API key.
Payments
https://app.hyperswitch.io/api/analytics/v1/merchant/report/payments
Refunds
https://app.hyperswitch.io/api/analytics/v1/merchant/report/refunds
Disputes
https://app.hyperswitch.io/api/analytics/v1/merchant/report/dispute
Payouts
https://app.hyperswitch.io/api/analytics/v1/merchant/report/payouts
Authentications
https://app.hyperswitch.io/api/analytics/v1/merchant/report/authentications
The API key identifies the Merchant. You do not need to pass a Merchant ID in the endpoint or request body.
Profile-Level Endpoints
Use these endpoints with the X-Profile-Id header to generate a report for a specific Profile.
Payments
https://app.hyperswitch.io/api/analytics/v1/profile/report/payments
Refunds
https://app.hyperswitch.io/api/analytics/v1/profile/report/refunds
Disputes
https://app.hyperswitch.io/api/analytics/v1/profile/report/dispute
Payouts
https://app.hyperswitch.io/api/analytics/v1/profile/report/payouts
Authentications
https://app.hyperswitch.io/api/analytics/v1/profile/report/authentications
Production Endpoints
Contact the Hyperswitch team to get the production report endpoints for your account. Use your production API key and allowlist the production webhook URL before going live.
Request Parameters
Headers
api-key
Required
Required
Your secret Hyperswitch API key
Content-Type: application/json
Required
Required
Identifies the request body as JSON
X-Profile-Id
Not required
Required
Identifies the Profile for the report
Request Body
timeRange
Yes
Contains the report start and end times
timeRange.startTime
Yes
Start time in ISO 8601 format
timeRange.endTime
No
End time in ISO 8601 format. Defaults to the current time
emails
Yes
A non-empty array containing at least one valid email address
returnUrl
Yes
The allowlisted HTTPS endpoint that receives the completed report webhook
Use UTC timestamps with millisecond precision, such as 2026-06-15T00:00:00.000Z.
Note: The
emailsarray is currently required for API-key requests, even when the report is delivered through a webhook. If the field is missing or empty, the API returns HTTP400with error codeIR_06.
Note:
timeRange.endTimeis optional. We recommend sending it when you need a fixed and repeatable reporting period.
Step 1: Configure Your Webhook Endpoint
Set up a dedicated endpoint on your server to receive the completed report webhook.
Your returnUrl must:
use HTTPS
be accessible from the public internet
be allowlisted by the Hyperswitch team(for production)
accept
POSTrequests with a JSON body
Share the exact sandbox and production URLs with the Hyperswitch team if you use different endpoints for each environment.
Step 2: Trigger Report Generation
Merchant-Level Request
The following example generates a Merchant-level Payments report in sandbox:
Change the endpoint suffix to generate another supported report type.
Profile-Level Request
For a Profile-level report, use the Profile endpoint and include X-Profile-Id:
API Response
Hyperswitch returns HTTP 200 after accepting the report request. The response body can be JSON null.
This response is only an acknowledgement. The report is generated asynchronously and is not included in the API response.
Step 3: Receive the Webhook
When the report is ready, Hyperswitch sends a POST request to your returnUrl.
The request includes the following signature header:
The webhook payload has the following structure:
The report is available at data.download_url. The webhook does not contain the CSV file itself.
Field reference
event_type
Event type. This is always report_generation.completed.
status
Report generation status. success means the report was generated and uploaded successfully.
org_id
Organization ID associated with the report.
merchant_id
Merchant ID associated with the report.
data.report_type
Report type. Possible values are payment_report, refund_report, dispute_report, payout_report, and authentication_report.
data.start_date_utc
Start date of the reporting period in YYYY-MM-DD UTC format.
data.end_date_utc
End date of the reporting period in YYYY-MM-DD UTC format.
data.download_url
Pre-signed AWS S3 URL for downloading the generated CSV report. The webhook payload does not contain the report itself.
data.expires_in_hours
Number of hours before the download URL expires, typically 48. Generate a new report if the URL has expired.
Failure event
If report generation fails, Hyperswitch sends a report_generation.failed event to your returnUrl.
The failure payload does not contain a report download URL.
Failure event JSON body
Field reference
event
Event type. This is always report_generation.failed for report generation failures.
org_id
Organization ID associated with the report request.
merchant_id
Merchant ID associated with the report request.
data.code
Machine-readable error code that identifies the failure.
data.message
Description of the failure and the recommended action.
Handling a failure event
When you receive a failure event:
Record the error code and message for monitoring.
Submit a new report request.
Contact the Hyperswitch team if the failure continues.
Step 4: Verify the Webhook Signature(Optional)
Hyperswitch signs the exact request body using HMAC-SHA512 and the payment_response_hash_key associated with the Merchant or Profile.
To validate the webhook:
Read the exact raw request body.
Read the
X-Webhook-Signature-512header.Generate an HMAC-SHA512 signature using the raw body and
payment_response_hash_key.Fetch
payment_response_hash_keyfrom payment settings in hyperwitch control center.Compare the generated and received signatures in constant time.
Reject the webhook if the signatures do not match.
Python example:
Important: Do not parse and recreate the JSON before signature verification. Any change to the original request body can produce a different signature.
Step 5: Download the Report
After verifying the signature, download the CSV file from data.download_url.
The pre-signed URL usually expires after 48 hours. Download and store the report before the value in data.expires_in_hours is reached.
Security Warning: Do not expose or log the complete
download_url. Anyone with access to the URL may be able to download the report until it expires.
Report Limit
Each generated report can contain up to 50,000 rows.
If your report may exceed this limit:
Split the reporting period into smaller, non-overlapping time ranges.
Generate one report for each time range.
Combine the downloaded CSV files in your system.
Reports that exceed the limit are not automatically paginated.
For endpoint allowlisting and integration support, contact the Hyperswitch team through your usual support channel.
Last updated
Was this helpful?

