Skip to main content

​
Overview

Atlantic supports webhooks to notify your application about query status changes in real-time. Instead of polling the API to check query status, you can configure a webhook URL to receive automatic notifications when important events occur.

​
Webhook Events

Atlantic can send two types of webhook events:

​
ATLANTIC_STEP_COMPLETED

Triggered when an individual step of your Atlantic query completes (e.g., trace generation, proof generation, verification).

​
ATLANTIC_QUERY_COMPLETED

Triggered when the entire Atlantic query completes successfully or fails.

​
Webhook Payload Structure

When an event occurs, Atlantic will send a POST request to your configured webhook URL with the following JSON payload: 
{
  "type": "ATLANTIC_STEP_COMPLETED" | "ATLANTIC_QUERY_COMPLETED",
  "atlanticQueryId": "your-query-id",
  "status": "completed" | "failed",
  "context": null | {
    // Additional context data specific to the event
  },
  "jobName": "trace-generation", // Optional: Name of the completed job
  "error": null | {
    // Error details if status is "failed"
  }
}

​
Payload Fields

FieldTypeDescription
typestringThe type of webhook event (ATLANTIC_STEP_COMPLETED or ATLANTIC_QUERY_COMPLETED)
atlanticQueryIdstringThe unique identifier of your Atlantic query
statusstringThe status of the query or step (e.g., completed, failed)
contextobject | nullAdditional context information about the event
jobNamestring(Optional) The name of the completed job/step
errorobject | null(Optional) Error details if the query or step failed

​
Configuring Webhooks

You can configure a webhook URL for each project separately through the Herodotus Cloud console. This allows you to set up different webhook endpoints for different projects based on your needs.

​
Setting up Webhooks via Console

  1. Navigate to your project page at https://www.herodotus.cloud/en/projects/{PROJECT_ID}
  2. Locate the Webhook URL section
  3. Enter your webhook endpoint URL (must be a publicly accessible HTTPS URL)
  4. Click Save to apply the configuration
Webhook URL Configuration Once configured, all Atlantic queries submitted within that project will automatically send webhook notifications to the specified URL when events occur.

​
Implementing a Webhook Endpoint

Your webhook endpoint should:
  1. Accept POST requests with JSON payload
  2. Respond quickly (within a few seconds) with a 2xx status code
  3. Handle retries gracefully (Atlantic may retry failed webhook deliveries)

Submit Query

Learn how to submit queries with webhook configuration

Query Status

Understand query statuses and states

Get Query

Fetch query details and results

Examples

See complete examples of using Atlantic
⌘I