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

# Webhooks

> Receive real-time notifications about events in Forerunner

## Overview

Webhooks enable you to receive real-time notifications when specific events occur in Forerunner. Instead of polling the API, your application can be notified immediately when files are processed, records are updated, or other important events happen.

## How Webhooks Work

<Steps>
  <Step title="Configure your webhook endpoint">
    Set up an HTTPS endpoint on your server that can receive POST requests from Forerunner. We recommend writing one endpoint capable of handling all webhook payloads.
  </Step>

  <Step title="Register with Forerunner">
    Contact your CS representative with your HTTPS endpoint URL and any required
    authentication headers to enable webhook delivery.
  </Step>

  <Step title="Receive webhooks">
    When a relevant event occurs, Forerunner sends HTTP POST requests to your
    endpoint with the results.
  </Step>

  <Step title="Process and respond">
    Your endpoint processes the data and returns a `2XX` status code to acknowledge receipt.
  </Step>
</Steps>

***

## Request Headers

Every webhook request includes the following HTTP headers:

| Header         | Value              |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |

Additional authentication headers can be configured upon request.

***

## Webhook payloads

Forerunner sends webhooks for specific events in your account. Each event type has its own payload structure.

### Document finished processing

Sent when a document finishes processing, including OCR, validation, and data extraction. This is the primary webhook for tracking file processing status.

<Expandable title="payload">
  <ParamField body="file" type="object">
    Document processing result

    <Expandable title="file properties">
      <ParamField body="id" type="string">
        A UUID that uniquely identifies the file in Forerunner
      </ParamField>

      <ParamField body="status" type="enum">
        <ul>
          <li>
            `completed`: The document was fully processed and evaluated for
            errors.
          </li>

          <li>
            `canceled`: The document's processing was cancelled due to a variety
            of reasons, such as the contents of the file not matching up with
            the file type.
          </li>

          <li>
            `needs_location`: The document finished processing, but requires
            someone to visit Forerunner to adequately geolocate the property.
          </li>
        </ul>
      </ParamField>

      <ParamField body="url" type="string">
        URL to view the document in Forerunner
      </ParamField>

      <ParamField body="validationIssues" type="array">
        Any issues with how the document was filled out. Note that these are
        validation issues with the *document* itself, not with the processing of
        said document. A canceled document will not include validation issues.

        <Expandable title="validation issue properties">
          <ParamField body="type" type="enum">
            <ul>
              <li>
                `error`: Indicates that the document was filled out incorrectly
                in one or more places and requires immediate attention.
              </li>

              <li>
                `warning`: Indicates that something looks amiss but not
                critically so.
              </li>
            </ul>
          </ParamField>

          <ParamField body="errorCode" type="string">
            A machine-readable code that uniquely identifies the issue
          </ParamField>

          <ParamField body="fieldText" type="string">
            The field or input in the document the issue pertains to (e.g., "A7.
            Building Diagram Number" for elevation certificates)
          </ParamField>

          <ParamField body="issue" type="string">
            A string describing the actual issue. Combined with `fieldText`,
            this can be used to compose user-readable messages.
          </ParamField>
        </Expandable>
      </ParamField>
    </Expandable>
  </ParamField>
</Expandable>

<Expandable title="sample payload">
  ```json theme={null}
  {
    "file": {
      "id": "26f5bc67-a96a-42be-904e-6e1bab6b73b6",
      "status": "completed",
      "url": "https://app.withforerunner.com/files/26f5bc67-a96a-42be-904e-6e1bab6b73b6",
      "validationIssues": [
        {
          "type": "warning",
          "errorCode": "c2eBlankOrNA",
          "fieldText": "C2.e Lowest elevation of machinery or equipment",
          "issue": "C2.e should be filled out, unless the structure is outside of the SFHA or it's a building type that does not have any machinery/equipment (M/E) servicing the building."
        }
      ]
    }
  }
  ```
</Expandable>

***

## Retry Policy

Forerunner implements automatic retries for failed webhook deliveries. If your server returns a non-`2XX` HTTP status code, Forerunner will retry the webhook request up to 2 times using an exponential backoff algorithm to avoid overwhelming your server.

***

## Troubleshooting

### Webhook not received

<Steps>
  <Step title="Verify endpoint accessibility">
    Ensure your endpoint is publicly accessible via HTTPS
  </Step>

  <Step title="Check firewall rules">
    Confirm your firewall allows incoming requests from Forerunner's IP ranges
  </Step>

  <Step title="Review server logs">
    Check for incoming requests and any errors in your application logs
  </Step>

  <Step title="Test with curl">
    Send a test POST request to verify your endpoint works:

    ```bash theme={null}
    curl -X POST https://your-domain.com/your-webhook-url \
      -H "Content-Type: application/json" \
      -d '{"file":{"id":"test123","status":"completed","url":"https://example.com/documents/test123","validationIssues":[]}}'
    ```
  </Step>
</Steps>