> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prophic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations and Webhooks REST API Reference

> Full contracts for the Prophic partner integrations API and the organization webhook configuration API, including endpoints, payloads, and errors.

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.

<Tip>
  For a plain-language walkthrough, see the [integrations overview](/integrations/overview). Interactive OpenAPI docs are served by the API at `/api-docs`.
</Tip>

## 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`

```json theme={null}
{
  "quotation_id": "<uuid>",
  "status": "<pipeline status string>"
}
```

**Example:**

```bash theme={null}
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`

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

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

### 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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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](/integrations/api-keys) for the full workflow.

## Related

<CardGroup cols={2}>
  <Card title="Integrations Overview" icon="plug" href="/integrations/overview">
    Plain-language walkthrough of the end-to-end flow.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/integrations/webhooks">
    Signature verification and delivery details.
  </Card>
</CardGroup>


## Related topics

- [Receive Prophic Pipeline Events with Webhooks](/integrations/webhooks.md)
- [Connect Prophic to Your CRM, Portal, or Automation](/integrations/overview.md)
- [Create and Manage Prophic API Keys](/integrations/api-keys.md)
- [27 Client Discovery Questions Before You Quote a Project](/resources/discovery-questions.md)