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

A webhook tells your application that an Elevation Certificate you uploaded through the API has finished processing, so you do not have to poll for it. It is the only webhook Forerunner sends today.

## 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 Customer Success Manager 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

### Document finished processing

Sent when an Elevation Certificate uploaded through `POST /api/v1/files` finishes processing, including OCR, validation, and data extraction. Documents of other types, and certificates uploaded through the Forerunner app rather than the API, do not produce a webhook.

<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. It is the same
        `id` the Files API returns, so you can fetch the file's metadata with
        `GET /api/v1/files/{id}`.
      </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">
        Link to the file in Forerunner, on your account's subdomain. Requires an
        account to open.
      </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://demoville.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

If your server returns a non-`2XX` HTTP status code, Forerunner retries the request up to 2 times with exponential backoff. After the third failed attempt the delivery is dropped, so treat your endpoint's availability as the delivery guarantee.

***

## 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 accepts requests from Forerunner. We do not publish a
    fixed set of source IP addresses, so authenticate on the headers you
    registered rather than on the source address.
  </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":"26f5bc67-a96a-42be-904e-6e1bab6b73b6","status":"completed","url":"https://demoville.app.withforerunner.com/files/26f5bc67-a96a-42be-904e-6e1bab6b73b6","validationIssues":[]}}'
    ```
  </Step>
</Steps>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.