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

# Webhooks

> Receive real-time Audity events at your own HTTPS endpoint.

Audity can push events to any HTTPS endpoint you control. Use webhooks to trigger downstream workflows the moment a survey is completed or an analysis is ready, no polling required.

## Requirements

* **Solo, Team, or Enterprise** plan
* An HTTPS endpoint that returns a `2xx` status within **10 seconds**
* The endpoint URL must begin with `https://`, plain HTTP is not accepted

## Configure your endpoint

<Steps>
  <Step title="Open webhook settings">
    In the Audity app, go to **Dashboard → Settings → Webhook**.
  </Step>

  <Step title="Enter your endpoint URL">
    Paste your HTTPS endpoint URL. Audity validates that the URL scheme is `https` before saving.
  </Step>

  <Step title="Select events">
    Choose one or more events to subscribe to (see [Events](#events) below).
  </Step>

  <Step title="Save and verify">
    Click **Save**. Audity will attempt a test delivery to confirm the endpoint is reachable.
  </Step>
</Steps>

## Events

| Event                | Triggered when                                     |
| -------------------- | -------------------------------------------------- |
| `survey_completed`   | A respondent submits the last question in a survey |
| `analysis_generated` | An audit analysis finishes generating              |

## Payload format

All deliveries include an `X-Audity-Event` header with the event name and an `X-Audity-Delivery` header with a unique delivery ID.

Payloads are JSON. Use the `version` field to distinguish payload versions.

<CodeGroup>
  ```json v1 theme={null}
  {
    "version": "1",
    "event": "survey_completed",
    "timestamp": "2025-05-01T14:32:00Z",
    "data": {
      "projectId": "proj_abc123",
      "surveyId": "srv_xyz789",
      "respondentId": "resp_def456",
      "completedAt": "2025-05-01T14:31:58Z"
    }
  }
  ```

  ```json v2 theme={null}
  {
    "version": "2",
    "event": "survey_completed",
    "timestamp": "2025-05-01T14:32:00Z",
    "deliveryId": "dlv_gh1234",
    "data": {
      "projectId": "proj_abc123",
      "surveyId": "srv_xyz789",
      "respondentId": "resp_def456",
      "completedAt": "2025-05-01T14:31:58Z",
      "meta": {
        "clientName": "Acme Corp",
        "auditType": "360"
      }
    }
  }
  ```
</CodeGroup>

<Note>
  The `version` field is always present. Build your receiver to inspect `version` before parsing `data`, so older integrations continue to work when you upgrade to v2.
</Note>

## Retry behavior

If your endpoint returns a non-`2xx` status or does not respond within 10 seconds, Audity retries the delivery up to **3 times** using exponential backoff:

| Attempt   | Delay        |
| --------- | ------------ |
| 1st retry | \~30 seconds |
| 2nd retry | \~5 minutes  |
| 3rd retry | \~30 minutes |

After 3 failed attempts the delivery is marked as permanently failed. Check the delivery log in **Settings → Webhook** to inspect failures and replay individual deliveries manually.

## GHL (GoHighLevel) setup example

To push Audity survey events into a GoHighLevel workflow:

<Steps>
  <Step title="Create a GHL inbound webhook trigger">
    In GHL, open **Automation → Workflows** and create a new workflow. Add an **Inbound Webhook** trigger. Copy the generated webhook URL.
  </Step>

  <Step title="Register the URL in Audity">
    Paste the GHL webhook URL into **Settings → Webhook** in Audity. GHL inbound webhook URLs are always `https://`, so no modification is needed.
  </Step>

  <Step title="Map payload fields">
    In your GHL workflow, use the inbound payload fields (e.g. `data.projectId`, `data.clientName`) to branch logic or update contact records.
  </Step>

  <Step title="Test end-to-end">
    Complete a test survey in Audity. You should see the delivery appear in GHL's workflow execution history within seconds.
  </Step>
</Steps>

## Error reference

| Code                      | Meaning                                        | Resolution                                                                                    |
| ------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `WEBHOOK_HTTPS_REQUIRED`  | The endpoint URL does not use HTTPS            | Update your URL to start with `https://`                                                      |
| `WEBHOOK_TIMEOUT`         | The endpoint did not respond within 10 seconds | Optimize your receiver to return `200` immediately and process the payload asynchronously     |
| `WEBHOOK_DELIVERY_FAILED` | All 3 retry attempts failed                    | Check your endpoint logs, fix the issue, then replay the delivery from **Settings → Webhook** |

## What's next

* [Use webhooks to trigger n8n workflows →](/guide/integrations/n8n)
* [Generate a Gamma deck from audit deliverables →](/guide/integrations/gamma)