Callbacks

You can receive updates about your submissions by registering callbacks. These are HTTP POST messages that our system sends to you.

There are two types of callbacks:

1. Submission Status Change Callbacks - sent when a submission's status changes
2. Submission Event Callbacks - sent when specific events occur during submission processing

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. You may also configure callbacks for all submissions on your org. Contact us if you want to set this up.

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

Submission Status Change Callbacks

These callbacks are sent whenever a submission's status changes. The format of a submission status change 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.

Submission Event Callbacks

These callbacks are sent when specific events occur during submission processing. Currently, we send submission event callbacks for file retrieval errors. Additional event types may be added in the future.

The format of a submission event callback is:

{
  "message_type": "submission_event",
  "event": {
    "event_type": "file_retrieval_error",
    "submission_id": "9973ec60-2be5-4fb0-9212-81111bdc434f",
    "url": "https://example.com/file.pdf",
    "response_status": 404,
    "message": "Unexpected status code"
  }
}

There is currently only one event type:

• file_retrieval_error - Sent when a file cannot be downloaded from a provided URL. Includes the URL, HTTP response status, and error message.

Failure Modes

We will retry a callback up to 3 times with 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.
3. If you have a single callback URL, let us know and we will configure it for all submissions.

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.