Callbacks

You can receive updates about changes to your submission by registering a callback. These are HTTP POST messages that our system sends to you.

Callbacks must be to a domain that we recognize and that you control. We will send a shared secret to your HTTP endpoint with the message. See Auth Headers.

When you send a Submission, include the callback_url field. We will send updates to this endpoint.

If you are a Service Provider and want to receive callbacks for submissions sent by another system, you can configure these via Oversight.

Format

The format of a callback is:

{
  "submission": {
      "id": "9973ec60-2be5-4fb0-9212-81111bdc434f",
      "status": "report-available",
      "created_by": "clear-skies/YOUR_ACCOUNT_ID",
      "created": "2025-02-19T17:47:14.370440Z",
      "updated": "2025-02-19T17:47:14.376194Z",
      "app_report_link": "https://PATH_TO_WEBAPP"
  }
}

The status will be one of the values described in Lifecycle.

Failure Modes

We will retry a callback up to 3 times with exponential back-off until we receive an HTTP 200 or HTTP 300 response. After that, we will stop retrying.

Checklist

1. Please contact us to request authorization for your domain.
2. Please supply a shared secret that we can send.

Service providers:

1. Ensure that the Customer has enabled "Read" access for all relevant sites.
2. Navigate to Menu -> Organization -> Customer Sites.
3. Set the callback URL to your URL.