Webhooks

Webhook endpoints are registered through the signed partner API. PayFi can keep multiple endpoints per partner integration, and each endpoint declares which events it wants to receive. PayFi only sends HTTPS callbacks and blocks localhost, private IP, link-local, metadata, and credential-bearing URLs. Payloads are redacted: raw documents, prompts, completions, secrets, signatures, presigned URLs, and full tax IDs are never sent.

Manage endpoints

Use the same PayFi partner authentication headers used by the rest of the API.

GET /v1/webhooks
POST /v1/webhooks
GET /v1/webhooks/{webhookId}
PATCH /v1/webhooks/{webhookId}
DELETE /v1/webhooks/{webhookId}
POST /v1/webhooks/{webhookId}/test

Create request:

{
  "name": "Acme endpoint",
  "url": "https://acme.example/payfi/webhooks",
  "eventTypes": [
    "operation.created",
    "operation.requirements.ready",
    "operation.analysis.completed",
    "operation.action_required",
    "operation.manual_review.completed"
  ]
}

PayFi generates the webhook signing secret and returns it only in the create response or when rotateSecret is true on update. Store it immediately.

Events

Supported events:

operation.created
operation.requirements.ready
operation.documents.partial
operation.analysis.completed
operation.action_required
operation.manual_review.completed
operation.callback.failed

operation.callback.failed is emitted to other subscribed endpoints when a delivery fails terminally. PayFi does not recursively emit operation.callback.failed for a failed callback-failed delivery.

Event	When PayFi emits it	Operational meaning
`operation.created`	After `POST /v1/operations` creates the operation.	The partner can show the PayFi operation ID while initial requirements are pending.
`operation.requirements.ready`	After the initial document requirement assessment is ready or auto-approved.	The partner can review the list or start approved document collection.
`operation.documents.partial`	After document completeness changes and at least one required document is still missing.	The partner should ask the customer for the missing document types in the payload.
`operation.analysis.completed`	After analysis finishes and the operation is ready for human review.	Compliance evidence is available; the final decision is still manual.
`operation.action_required`	After analysis or completeness checks find missing evidence or low-confidence data.	The partner should pause the operation and collect the requested material.
`operation.manual_review.completed`	After an authorized reviewer records approval, rejection, or changes requested.	This is the final human decision notification for the partner workflow.
`operation.callback.failed`	After a different delivery reaches terminal failure.	This is an operational alert for webhook processing, not a compliance decision.

Payload

The API Reference includes one schema per event:

WebhookOperationCreatedPayload
WebhookDocumentsPartialPayload
WebhookAnalysisCompletedPayload
WebhookActionRequiredPayload
WebhookManualReviewCompletedPayload
WebhookCallbackFailedPayload

All events share the same top-level shape so partners can route by event first and then apply event-specific rules. Default shape:

{
  "event": "operation.analysis.completed",
  "operationId": "op_example",
  "partnerOperationId": "acme-op-123",
  "status": "READY_FOR_MANUAL_REVIEW",
  "score0To100": 82,
  "score1To10": 9,
  "riskLevel": "medium",
  "missingDocumentTypes": [],
  "actionRequired": false,
  "manualApprovalRequired": true,
  "analysisRunId": "job_example",
  "manualReviewDecision": null,
  "processedAt": "2026-05-20T12:00:00.000Z"
}

Do not treat webhook delivery as the source of truth for PayFi state. The source of truth remains GET /v1/operations/{operationId}.

End-to-end flow

The partner creates one or more webhook endpoints with POST /v1/webhooks.
PayFi validates the signed partner request, reserves the idempotency key, validates the URL, generates a signing secret, stores the encrypted secret, and returns the plaintext secret once.
When an operation changes state, PayFi selects active endpoints subscribed to that event.
PayFi builds the allowlisted payload, redacts it, serializes it to raw JSON, hashes the raw body, and persists a WebhookDelivery before any HTTP call.
The worker loads due deliveries, reloads the endpoint, revalidates that it is active and has a safe URL, decrypts the endpoint secret, verifies the stored payload hash, signs the exact raw JSON body, and sends the callback.
PayFi persists every attempt with status, response status, response body hash, request header hash, duration, failure code, and attempted timestamp.
A 2xx response marks the delivery as DELIVERED. A retryable failure sets RETRY_SCHEDULED and nextAttemptAt. A terminal failure marks the delivery as FAILED.

Registration validations

Webhook management endpoints use the same partner request signing model as the rest of the API:

X-PayFi-Api-Key
X-PayFi-Nonce
X-PayFi-Signature
Idempotency-Key on create, update, delete, and test requests

PayFi validates:

API key is active and scoped to the partner integration.
Nonce has not been replayed.
Request timestamp is inside the allowed skew.
HMAC signature matches the exact raw request body.
Idempotency key is reused only with the same method, path, and body hash.
Webhook ID belongs to the signed partner integration.
URL uses HTTPS and does not include credentials.
URL host is not localhost, private IP, link-local, or metadata infrastructure.
eventTypes contains only supported event names.
Signing secrets are generated server-side and returned only on create or explicit rotation.

Delivery validations

Before each HTTP delivery attempt, PayFi validates the stored delivery again:

Endpoint still exists, is active, and belongs to the same organization and partner integration.
Endpoint URL still passes SSRF validation.
Endpoint signing secret decrypts successfully.
Re-serialized payload hash matches the persisted payloadHash.
Payload is signed with the exact raw JSON body that will be sent.
Response bodies are hashed for auditability; raw response bodies are not stored.
Authorization headers, webhook secrets, signatures, raw documents, prompts, completions, and full tax IDs are never written into delivery logs.

These checks happen on retries too, so disabling an endpoint or rotating a secret affects future attempts without changing already persisted delivery payloads.

Signature verification

PayFi signs the exact raw JSON body and sends:

x-payfi-webhook-id: whd_example
x-payfi-webhook-timestamp: 1779000000000
x-payfi-webhook-signature: t=1779000000000,d=whd_example,h=<sha256_body>,v1=<hmac_sha256>

Signature base string:

<timestampMs>.<deliveryId>.<sha256(rawJsonBody)>

Use the webhook signing secret as the HMAC-SHA256 key. Verify the signature before parsing business fields, using the exact raw body bytes received by your HTTP server.

Retries

PayFi retries transient partner processing failures:

network errors
timeout
HTTP 408
HTTP 429
any HTTP 5xx

Terminal failures:

any HTTP 2xx: delivered
HTTP 4xx except 408 and 429: failed

Retry schedule:

Attempt	Next retry
1	1 minute
2	5 minutes
3	15 minutes
4	1 hour
5	4 hours
6	12 hours
7	24 hours
8	terminal failure

Partners should make webhook handlers idempotent by storing the x-payfi-webhook-id header or a tuple of event and operationId.

Test delivery

POST /v1/webhooks/{webhookId}/test sends one signed sample payload to the endpoint. Test deliveries do not schedule retries, so a failed test response is terminal for that test request.

Integration

Trust and release

Authentication

Manage endpoints

Events

Payload

End-to-end flow

Registration validations

Delivery validations

Signature verification

Retries

Test delivery

​Manage endpoints

​Events

​Payload

​End-to-end flow

​Registration validations

​Delivery validations

​Signature verification

​Retries

​Test delivery

Manage endpoints

Events

Payload

End-to-end flow

Registration validations

Delivery validations

Signature verification

Retries

Test delivery