Webhooks

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

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

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.

Show payload

object

Document processing result

Show file properties

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}.

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

Link to the file in Forerunner, on your account’s subdomain. Requires an account to open.

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

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

Verify endpoint accessibility

Ensure your endpoint is publicly accessible via HTTPS

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.

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":"26f5bc67-a96a-42be-904e-6e1bab6b73b6","status":"completed","url":"https://demoville.app.withforerunner.com/files/26f5bc67-a96a-42be-904e-6e1bab6b73b6","validationIssues":[]}}'

Getting started

Endpoints

Concepts

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