Report Webhooks

    What you are going to learn:

  • What are the report webhooks
  • How to configure a report webhook

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 Signature (optional): Learn more on Webhook Signatures

Webhook retries
Webhook retries

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

Webhook HTTP Body
Webhook HTTP Body

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"
  }
}

Download Report
Download Report

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://..."
}