Report Webhooks

For customers who want to automate reporting, it is possible to receive a HTTP POST Webhook when a report is completed. For both the report and the report schedule, it is possible to configure:

• Webhook URL: Endpoint URL
• Webhook Secrets (optional): Learn more on Webhook Secrets

If the Webhook doesn't return a status code between 200 and 299, the webhook will be retried up to 10 times with exponentional sleep time between requests from 1 minute up to 1 hour. After 10 retries, the webhook will not be retried.

Here is an example of the HTTP body:

{
  "type": "report",
  "created": 1669317365,
  "data": {
    "id": "ABCEDEFGHIJKLMNOPQRSTUVWXYZ",
    "org_id": 700412,
    "name": "WH 3",
    "created_ts": 1669317345,
    "completed_ts": 1669317365,
    "start_date": "2022-11-24 14:14",
    "end_date": "2022-11-24 14:15",
    "status": "completed",
    "user": "support@obkio.com",
    "public_url": true,
    "webhook": "https://mydomain.com/obkio_webhook/",
    "webhook_attempts": 1,
    "timezone": "America/Montreal",
    "downloads": 0,
    "url": "https://reports.dev.obkio.com/d/ABCEDEFGHIJKLMNOPQRSTUVWXYZ/123ABC123ABC123A/",
    "config": {
      "type": "config",
      "json": true
    },
    "size": 53066,
    "extensions": [
      "json",
      "xlsx"
    ],
    "filename": "obkio-report-config-ABCEDEFGHIJKLMNOPQRSTUVWXYZ.zip"
  }
}

There are two ways to download the report when a webhook is received. The easiest one is to use the public URL in the field url of the body. This URL doesn't require any authentication.

The second option is using the webhook secret provided when the report has been generated to generate a webhook signature to authenticate the request. The request must use a HTTP GET method to the endpoint https://reports.obkio.com/signed_download/{report_id}. The header x-obkio-signature must be added with a valid Obkio Webhook Signature v1. On success, the endpoint will return a 200 status code with a signed URL valid for 5 minutes:

{
  "url": "https://..."
}