> ## Documentation Index
> Fetch the complete documentation index at: https://docs.herodotus.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Configure webhooks to receive real-time notifications about Atlantic query progress

## 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:

```json theme={null}
{
  "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

| Field             | Type             | Description                                                                         |
| ----------------- | ---------------- | ----------------------------------------------------------------------------------- |
| `type`            | `string`         | The type of webhook event (`ATLANTIC_STEP_COMPLETED` or `ATLANTIC_QUERY_COMPLETED`) |
| `atlanticQueryId` | `string`         | The unique identifier of your Atlantic query                                        |
| `status`          | `string`         | The status of the query or step (e.g., `completed`, `failed`)                       |
| `context`         | `object \| null` | Additional context information about the event                                      |
| `jobName`         | `string`         | *(Optional)* The name of the completed job/step                                     |
| `error`           | `object \| 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

<img src="https://mintcdn.com/herodotuscloudservices/50DyPzBRWMEGx5J9/images/atlantic/webhook-url-config.png?fit=max&auto=format&n=50DyPzBRWMEGx5J9&q=85&s=8e3cc3dd96a196225f71cc2acd45a974" alt="Webhook URL Configuration" width="2402" height="462" data-path="images/atlantic/webhook-url-config.png" />

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)

## Related Resources

<CardGroup cols={2}>
  <Card title="Submit Query" icon="paper-plane" href="/atlantic-api/endpoints/submit-query">
    Learn how to submit queries with webhook configuration
  </Card>

  <Card title="Query Status" icon="chart-line" href="/atlantic-api/status">
    Understand query statuses and states
  </Card>

  <Card title="Get Query" icon="magnifying-glass" href="/atlantic-api/endpoints/get-query">
    Fetch query details and results
  </Card>

  <Card title="Examples" icon="code" href="/atlantic-api/examples">
    See complete examples of using Atlantic
  </Card>
</CardGroup>