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.
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.
2
Register with Forerunner
Contact your CS representative with your HTTPS endpoint URL and any required
authentication headers to enable webhook delivery.
3
Receive webhooks
When a relevant event occurs, Forerunner sends HTTP POST requests to your
endpoint with the results.
4
Process and respond
Your endpoint processes the data and returns a 2XX status code to acknowledge receipt.
Sent when a document finishes processing, including OCR, validation, and data extraction. This is the primary webhook for tracking file processing status.
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.
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." } ] }}
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.
