Agreement signing outcome

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://docs.getpenfold.dev/mcp

Standard setup for AI tools providing an mcp.json file

      
          mcp.json

"Penfold Partner API MCP server": {
  "url": "https://docs.getpenfold.dev/mcp"
}

POST https://webhook.example.com

Bearer auth

Penfold POSTs a JSON body to your pre-registered webhook URL when a signing session reaches a terminal outcome. Exactly one event is emitted per signing session (no intermediate events).

Signature verification (`X-Penfold-Signature`)

Penfold signs every webhook with HMAC-SHA256 using a shared secret provisioned during onboarding.

Read the X-Penfold-Signature header. It contains comma-separated key/value pairs: t (Unix timestamp in seconds when Penfold sent the request) and v1 (lowercase hex-encoded HMAC-SHA256).
Construct the signing payload (UTF-8): {t}.{raw_body} — the string value of t, a literal ., then the raw JSON body bytes.
Compute HMAC-SHA256(secret, signing_payload), hex-encode, and compare to v1 in constant time.
Reject if |now_unix - t| > 300 (5-minute replay window).
Upsert by eventId for idempotency.

Delivery semantics

Return 2xx within 30 seconds.
On non-2xx, timeout, or no response: exponential backoff starting at 60 seconds, doubling each attempt, max interval 3600 seconds, up to 10 attempts within 24 hours.
After exhausted retries, events are not retried automatically.

application/json

Body Required

eventId string Required

Globally unique event id. Use for idempotent processing.
eventType string Required

Always EmployerAgreementSigningCompleted for this flow.

Value is EmployerAgreementSigningCompleted.
occurredAt string(date-time) Required

When Penfold recorded the terminal outcome (ISO 8601 UTC).
employerId string Required

Penfold employer id.
signingSessionId string Required

Same id as returned from create-session.
result string Required
Terminal outcome of a signing session. Closed enum — new values require a Partner API version bump.
- success: Signing journey completed successfully.
- cancelled: User intentionally exited without completing.
- failed: Technical, validation, or signature failure.
Values are success, cancelled, or failed.
failureCode string
Machine-readable reason when result is failed. Closed enum — new values require a Partner API version bump.
- tokenExpired: Signing session or URL token past TTL.
- sessionNotFound: Signing session unknown or not recognised.
- validationFailed: Validation failed during signing.
- providerUnavailable: Penfold or upstream dependency unavailable.
Values are tokenExpired, sessionNotFound, validationFailed, or providerUnavailable.

Responses

200

Webhook acknowledged.

POST EmployerAgreementSigningCompleted

Request examples

{
  "eventId": "PENEVT01999934D",
  "eventType": "EmployerAgreementSigningCompleted",
  "occurredAt": "2026-05-06T10:22:11.000Z",
  "employerId": "cmomwb1v7000dcalz2rf7ul5d",
  "signingSessionId": "cl9gujidl001o9ksfnrgr8zq1",
  "result": "success"
}

{
  "eventId": "PENEVT01999935E",
  "eventType": "EmployerAgreementSigningCompleted",
  "occurredAt": "2026-05-06T10:24:03.000Z",
  "employerId": "cmomwb1v7000dcalz2rf7ul5d",
  "signingSessionId": "cl9gujidl001o9ksfnrgr8zq1",
  "result": "cancelled"
}

{
  "eventId": "PENEVT01999936F",
  "eventType": "EmployerAgreementSigningCompleted",
  "occurredAt": "2026-05-06T10:25:44.000Z",
  "employerId": "cmomwb1v7000dcalz2rf7ul5d",
  "signingSessionId": "cl9gujidl001o9ksfnrgr8zq1",
  "result": "failed",
  "failureCode": "tokenExpired"
}