Integrations and Webhooks REST API Reference

The Prophic integrations platform exposes two surfaces. The partner integrations API authenticates with an API key and is used by external systems to start and read Quick Quotes. The organization webhook configuration API authenticates with a normal session and is used to manage webhook endpoints from the app.

For a plain-language walkthrough, see the integrations overview. Interactive OpenAPI docs are served by the API at /api-docs.

Partner integrations API

Base path: /v1/integrations Auth: X-API-Key: pk_... header only. Keys in the query string are rejected with 400. Org scope: taken from the key. Client-supplied organization IDs are ignored.

Rate limits

Limits apply per API key:

Scope	Limit	On exceed
All `/v1/integrations/*`	60 requests / minute	`429` + `Retry-After`
`POST /quotations` only	10 starts / minute (in addition to the general limit)	`429` + `Retry-After`

Common errors

Code	Meaning
`400`	Validation failure, or API key passed in the query string
`401`	Missing or invalid API key
`403`	Key inactive, expired, or revoked; or resource outside the key’s organization
`404`	Quotation, proposal, or document not found (in scope)
`429`	Rate limited

POST /v1/integrations/quotations

Start an async Quick Quote. Always non-blocking. Body (JSON or multipart):

Field	Type	Notes
`name`	`string \| null`	Optional
`description`	`string \| null`	Optional
`config_id`	`uuid \| null`	Quotation configuration
`requirementsText`	`string \| null`	RFP / requirements text
`metadata`	`object \| null`	Optional partner metadata
`files`	`file[]`	Multipart field `files` (max 5); `docx`, `pdf`, `txt`, `md`

Either requirementsText or at least one file is required. Quotes started here set Quotations.source = api_key and store the api_key_id. Success: 202 Accepted

{
  "quotation_id": "<uuid>",
  "status": "<pipeline status string>"
}

Example:

curl -X POST "$API/v1/integrations/quotations" \
  -H "X-API-Key: pk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme RFP","requirementsText":"Build a CRM with SSO"}'

GET /v1/integrations/quotations/:id

Quotation summary for the key’s organization. Success: 200

{
  "id": "<uuid>",
  "name": "...",
  "description": "...",
  "status": "...",
  "processed_step": "...",
  "source": "api_key",
  "config_id": "<uuid|null>",
  "error_code": null,
  "created_at": "...",
  "updated_at": "..."
}

The database field is source with values ui or api_key. Webhook lean payloads expose the same concept under generation_source.

GET /v1/integrations/quotations/:id/pipeline

Per-step pipeline status for the quotation. Returns the same shape as the internal pipeline status service. Success: 200 with a step list or progress object.

GET /v1/integrations/quotations/:id/proposal

Proposal metadata linked to the quotation. Success: 200

{
  "id": "<uuid>",
  "name": "...",
  "status": "...",
  "document_id": "<uuid|null>",
  "quotation_id": "<uuid>",
  "created_at": "...",
  "updated_at": "..."
}

GET /v1/integrations/proposals/:id/document-url

Short-lived signed URL for the proposal document. Returns 404 if the proposal has no document_id yet. Success: 200

{
  "url": "https://...",
  "expires_at": "2026-09-09T12:00:00.000Z"
}

Organization webhook configuration API

Base path: /v1/organizations/:organizationId/webhooks Auth: session-based (Clerk), same as the app. Permission: manage_integrations on all routes.

GET /webhooks/events

Event catalog with descriptions and example payloads (used by the settings UI).

GET /webhooks/deliveries

Recent delivery attempts for the organization. Query parameters:

Param	Notes
`endpoint_id`	Optional filter. Must belong to the org; soft-deleted endpoints are allowed for history.
`limit`	`1`–`100`, default `50`

Each attempt includes event_type, status, http_status, quotation_id, quotation_name (when resolvable), created_at, and related IDs.

GET /webhooks

List endpoints for the organization. Signing secrets are never included.

POST /webhooks

Create a webhook endpoint. Required body: name, url (HTTPS), events (non-empty array of catalog types). Optional: description, trigger_mode (headless_only or always), is_enabled. Success: endpoint object plus the one-time signing secret (whsec_...).

GET /webhooks/:id

Get one endpoint. The full secret is never returned.

PATCH /webhooks/:id

Update name, url, description, events, trigger_mode, and/or is_enabled.

DELETE /webhooks/:id

Soft-delete the endpoint. Historical delivery attempts remain available.

POST /webhooks/:id/rotate-secret

Issue a new signing secret. The response includes the new secret once.

POST /webhooks/:id/test

Send a signed sample lean payload for a subscribed event_type. Writes a delivery attempt row. Response includes a success flag, HTTP status, and optional error message.

Webhook event catalog

Stable event type strings delivered to partners:

Event type	When
`quotation.requirement_analysis.completed`	Requirement analysis step finished
`quotation.functional_specification.completed`	Functional specification finished
`quotation.work_breakdown.completed`	Work breakdown finished
`quotation.effort_estimation.completed`	Effort estimation finished
`quotation.proposal.completed`	Proposal artifact ready
`quotation.completed`	Full Quick Quote pipeline succeeded
`quotation.failed`	Pipeline run failed (terminal for that run)

Future domains (for example project.*) can be added without renaming these strings.

Delivery HTTP headers

Header	Purpose
`Content-Type`	`application/json`
`X-Prophic-Event-Id`	Same as payload `id`
`X-Prophic-Event-Type`	Event type string
`X-Prophic-Timestamp`	Unix seconds
`X-Prophic-Signature`	`v1=<hmac-sha256-hex>` over `timestamp + "." + rawBody`

Delivery uses HTTPS only with a ~10 second timeout and exponential backoff (up to 8 attempts). HTTP 410 is treated as permanent failure. Delivery is at-least-once.

Trigger modes

Mode	Behavior
`headless_only` (default)	Fire only when `generation_source` is `api_key`
`always`	Fire for UI and API-key quotes

API keys (session routes)

Partner keys are managed under the existing user API-key endpoints, not under /integrations:

Members can CRUD their own keys without manage_integrations.
Holders of manage_integrations can list and revoke any key in the organization.

The plaintext pk_... value is returned once at creation. After that only a masked form is shown. Keys support expiry, activate/deactivate, soft revoke, and last_used_at updates on successful authentication. UI: Account → API Keys. See API Keys for the full workflow.

Integrations Overview

Plain-language walkthrough of the end-to-end flow.

Webhooks

Signature verification and delivery details.

Get Started

Core Concepts

Setup

Working with Briefs

Integrations

Resources

Integrations and Webhooks REST API Reference

Partner integrations API

Rate limits

Common errors

POST /v1/integrations/quotations

GET /v1/integrations/quotations/:id

GET /v1/integrations/quotations/:id/pipeline

GET /v1/integrations/quotations/:id/proposal

GET /v1/integrations/proposals/:id/document-url

Organization webhook configuration API

GET /webhooks/events

GET /webhooks/deliveries

GET /webhooks

POST /webhooks

GET /webhooks/:id

PATCH /webhooks/:id

DELETE /webhooks/:id

POST /webhooks/:id/rotate-secret

POST /webhooks/:id/test

Webhook event catalog

Delivery HTTP headers

Trigger modes

API keys (session routes)

Integrations Overview

Webhooks

​Partner integrations API

​Rate limits

​Common errors

​POST /v1/integrations/quotations

​GET /v1/integrations/quotations/:id

​GET /v1/integrations/quotations/:id/pipeline

​GET /v1/integrations/quotations/:id/proposal

​GET /v1/integrations/proposals/:id/document-url

​Organization webhook configuration API

​GET /webhooks/events

​GET /webhooks/deliveries

​GET /webhooks

​POST /webhooks

​GET /webhooks/:id

​PATCH /webhooks/:id

​DELETE /webhooks/:id

​POST /webhooks/:id/rotate-secret

​POST /webhooks/:id/test

​Webhook event catalog

​Delivery HTTP headers

​Trigger modes

​API keys (session routes)

​Related

Integrations Overview

Webhooks

Partner integrations API

Rate limits

Common errors

POST /v1/integrations/quotations

GET /v1/integrations/quotations/:id

GET /v1/integrations/quotations/:id/pipeline

GET /v1/integrations/quotations/:id/proposal

GET /v1/integrations/proposals/:id/document-url

Organization webhook configuration API

GET /webhooks/events

GET /webhooks/deliveries

GET /webhooks

POST /webhooks

GET /webhooks/:id

PATCH /webhooks/:id

DELETE /webhooks/:id

POST /webhooks/:id/rotate-secret

POST /webhooks/:id/test

Webhook event catalog

Delivery HTTP headers

Trigger modes

API keys (session routes)

Related