Skip to content

Receive callback from external system

Request

Receive workflow completion callback from external systems (e.g., n8n).

URL format: /hooks/{projectKey}/executions/{executionId}/callback

Security:

  • Project key identifies tenant (RLS enforces isolation)
  • Execution ID is UUIDv4 (unguessable)
  • Execution must be < 1 hour old
  • Execution cannot receive multiple callbacks

No authentication required - security via execution ID secrecy + RLS.

Security
projectKey
Path
executionIdstringrequired

Webhook execution ID

projectKeyanyrequired

Project API key (same as in JWT callbackUrl)

Bodyapplication/jsonrequired
statusstringrequired

Callback status from external workflow

Enum:"NONE""SUCCESS""FAILED""CANCELLED"
Example:"SUCCESS"
resultobject

Result data from external workflow

errorstring

Error message if workflow failed

curl -i -X POST \
  'https://docs.pers.ninja/_mock/swagger/hooks/{projectKey}/executions/{executionId}/callback' \
  -H 'Content-Type: application/json' \
  -H 'x-project-key: YOUR_API_KEY_HERE' \
  -d '{
    "status": "SUCCESS",
    "result": {},
    "error": "string"
  }'

Responses

Callback processed successfully

Bodyapplication/json
idstringrequired

Execution ID

webhookIdobject

Webhook ID (set for proxy executions)

outboxEventIdobject

Outbox event ID (set for outbox dispatcher deliveries)

methodstringrequired

HTTP method

Example:"POST"
targetUrlstringrequired

Target URL at time of execution

statusstringrequired

Execution status

Enum:"PENDING""SUCCESS""FAILED""BLOCKED"
responseStatusCodenumber

HTTP response status code

durationMsnumber

Duration in milliseconds

sourceIpstringrequired

Source IP of the request

messagestring

Error or status message

startedAtstring, (date-time)required

When execution started

completedAtobject

When execution completed

callbackStatusstring

Callback status from external workflow

Default:"NONE"
Enum:"NONE""SUCCESS""FAILED""CANCELLED"
callbackResultobject

Callback result data from external workflow

callbackReceivedAtobject

When callback was received

Response
{
  "id": "string",
  "webhookId": {},
  "outboxEventId": {},
  "method": "POST",
  "targetUrl": "string",
  "status": "PENDING",
  "responseStatusCode": 0,
  "durationMs": 0,
  "sourceIp": "string",
  "message": "string",
  "startedAt": "2019-08-24T14:15:22Z",
  "completedAt": {},
  "callbackStatus": "NONE",
  "callbackResult": {},
  "callbackReceivedAt": {}
}