Skip to main content
Instead of polling the Reports API on a schedule, register a webhook endpoint that Connectly calls the moment a report run completes. The payload includes a signed URL so you can download the CSV immediately — no extra API call required.
The signed URL in a webhook payload expires after a few minutes only. Download the file immediately upon receiving the webhook. If the URL expires before you can download it, call the Reports API to retrieve a fresh one.

​
Registering the webhook

Use the Create webhook endpoint with "topic": "report": 
curl -X POST "https://api.connectly.ai/v1/businesses/{businessId}/create/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "report",
    "address": "https://yourdomain.com/connectly-webhooks",
    "type": "custom"
  }'
FieldDescription
topicMust be "report" to receive report completion events.
addressYour publicly accessible HTTPS endpoint.
typeSet to "custom" for a generic HTTP webhook.

​
Webhook payload

When a report run completes, Connectly POSTs the following payload to your endpoint: 
{
  "topic": "report",
  "timestamp": "2025-04-30T12:34:56Z",
  "report": {
    "id": "c80716a5-62c5-4ba5-b99d-5c2a6fd39317",
    "name": "Daily Campaign Report",
    "type": "campaign.daily.custom",
    "last_run": {
      "id": "run-001",
      "status": "completed",
      "result": {
        "url": "https://reports.connectly.ai/abcdef",
        "expires_at": "2025-05-01T12:34:56Z",
        "created_at": "2025-04-30T12:00:00Z"
      }
    }
  }
}
FieldDescription
topicAlways "report" for this webhook type.
timestampISO 8601 timestamp of when the webhook was sent.
report.idUnique ID of the report configuration.
report.nameHuman-readable report name.
report.typeReport type identifier.
report.last_run.idID of the completed run.
report.last_run.statusAlways "completed" when the webhook fires.
report.last_run.result.urlSigned URL to download the report CSV. Expires at expires_at.
report.last_run.result.expires_atWhen the signed URL expires — download immediately.
report.last_run.result.created_atWhen the report file was generated.
1

Acknowledge receipt immediately

Return a 2xx response as soon as you receive the webhook — before doing any processing. Connectly may retry if it doesn’t receive a timely acknowledgement.
2

Extract and validate the URL

Read report.last_run.result.url and check expires_at to confirm the URL is still valid.
3

Download the CSV immediately

Perform a GET request to the signed URL right away — it expires within minutes.
4

Handle expiry gracefully

If your handler is delayed and the URL has expired, call the Reports API to retrieve a fresh signed URL for the same report.
Your webhook endpoint must be reachable over HTTPS. Connectly does not deliver webhooks to plain HTTP addresses.