Webhooks

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

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.

Contact your CS representative with your HTTPS endpoint URL and any required authentication headers to enable webhook delivery.

Receive webhooks

When a relevant event occurs, Forerunner sends HTTP POST requests to your endpoint with the results.

Process and respond

Your endpoint processes the data and returns a 2XX status code to acknowledge receipt.

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.

Show payload

object

Document processing result

Show file properties

string

A UUID that uniquely identifies the file in Forerunner

enum

completed: The document was fully processed and evaluated for errors.
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.
needs_location: The document finished processing, but requires someone to visit Forerunner to adequately geolocate the property.

string

URL to view the document in Forerunner

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.

Show validation issue properties

enum

error: Indicates that the document was filled out incorrectly in one or more places and requires immediate attention.
warning: Indicates that something looks amiss but not critically so.

string

A machine-readable code that uniquely identifies the issue

string

The field or input in the document the issue pertains to (e.g., “A7. Building Diagram Number” for elevation certificates)

string

A string describing the actual issue. Combined with fieldText, this can be used to compose user-readable messages.

Show sample payload

{
  "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."
      }
    ]
  }
}

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

Verify endpoint accessibility

Ensure your endpoint is publicly accessible via HTTPS

Check firewall rules

Confirm your firewall allows incoming requests from Forerunner’s IP ranges

Review server logs

Check for incoming requests and any errors in your application logs

Test with curl

Send a test POST request to verify your endpoint works:

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":[]}}'

Getting started

API reference

Integration

Overview

How Webhooks Work

Request Headers

Webhook payloads

Document finished processing

Retry Policy

Troubleshooting

Webhook not received

​Overview

​How Webhooks Work

​Request Headers

​Webhook payloads

​Document finished processing

​Retry Policy

​Troubleshooting

​Webhook not received

Overview

How Webhooks Work

Request Headers

Webhook payloads

Document finished processing

Retry Policy

Troubleshooting

Webhook not received