Estimates

[Webhook] Trade report summary ready

This is not an API endpoint you call. This documents the webhook payload sent to your callbackUrl when a blueprint estimate's trade report summary finishes generating.

This is an opt-in feature — the webhook only fires for clients with the trade report summary feature enabled.

Webhook Details:

  • Trigger: A trade report summary is generated for a blueprint estimate version
  • Destination: Your callbackUrl provided in the estimate request
  • Method: POST
  • Headers:
    • Content-Type: application/json
    • User-Agent: Handoff-Enterprise-Webhook/1.0
    • X-Webhook-Attempt: <attempt_number>
    • Authorization: Bearer <access_token> (if outbound authentication is configured)
  • Expected Response: HTTP 2xx status code within 10 seconds
  • Retry Policy: Exponential backoff (1m, 5m, 15m, 1h, 6h)

Payload Structure:

  • event: Always trade_report_summary.ready
  • summary: The LLM-condensed trade report summary in markdown (the deliverable)
  • projectSummary: Overall project summary, if available
  • resultUrl: URL to re-fetch the summary (GET /v1/estimate/{id}/trade-report-summary, requires the trade_reports:read scope)
  • timestamp: ISO 8601 timestamp of when the summary was generated

Security:

  • Validate the resultUrl domain
  • Implement idempotency using estimateJobId + version
post/webhooks/trade-report-summary

Request

  • Base URL: https://api.handoff.ai
  • URL: https://api.handoff.ai/webhooks/trade-report-summary
  • Auth: none declared

Request body

event'trade_report_summary.ready' required

Webhook event type

estimateJobIdstring uuid required

Unique identifier for the estimate generation job

externalIdstring nullable required

Partner's internal estimate ID provided during job creation

versioninteger required

Version number of the estimate the summary was generated for (1, 2, 3, ...)

summarystring required

The LLM-condensed trade report summary in markdown

projectSummarystring nullable required

Overall project summary from the foundation index, if available

resultUrlstring uri required

URL to re-retrieve the trade report summary via GET request

timestampstring date-time required

ISO 8601 timestamp of when the summary was generated

Example request

{
  "event": "trade_report_summary.ready",
  "estimateJobId": "e1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
  "externalId": "EST-12345",
  "version": 1,
  "summary": "## Project Overview\n\n...\n\n## Framing\n\n...",
  "projectSummary": "Two-story single-family residence, 2,400 sqft ...",
  "resultUrl": "https://api.handoff.ai/v1/estimate/e1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c/trade-report-summary",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Response

Webhook received successfully

successboolean required

Example response

{
  "success": true
}

Changes

No recorded changes to this operation across all 1 revision of this API.