Postbacks

Overview

Postbacks let you receive an HTTP POST to a URL of your choice when a source reaches a final processing status. Use postbacks to avoid polling—your integration is notified as soon as processing finishes.

When postbacks are sent

A postback is sent when the source transitions to one of:

Configuration

Add postback_url to the instructions object when creating a source:

curl -X POST https://api.ctxfy.com/v1/spaces/{spaceId}/sources \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "CONTENT",
    "initial_data": {"data": "Your content here..."},
    "instructions": {
      "postback_url": "https://your-server.com/webhooks/ctxfy"
    },
    "name": "My Source"
  }'

The URL must be HTTPS and publicly reachable. Ctxfy sends a POST request to your endpoint when the source reaches a final status.

Postback payload

Your endpoint receives a JSON body:

{
  "event": "SourceStatusNotification",
  "sourceId": "uuid-of-the-source",
  "userId": "user-id",
  "spaceId": "space-id",
  "status": "COMPLETED",
  "message": "Optional error message for FAILED"
}

Best practices

1. Respond with 2xx — Your endpoint should return 200 (or any 2xx) quickly. Ctxfy may retry on non-2xx or timeout.

2. Implement idempotency — You may receive the same postback more than once (e.g. retries). Use sourceId + status to deduplicate and process each notification once.

3. Validate the request — Verify the request originates from Ctxfy (e.g. via signature header if supported; check docs for the latest options).

4. Handle asynchronously — Acknowledge the POST promptly and process the payload in a background job to avoid timeouts.

Alternative: polling

If postbacks are not suitable (e.g. behind a firewall), poll for status:

curl https://api.ctxfy.com/v1/sources/{sourceId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Check data.status for COMPLETED, FAILED, or CANCELED. See Quickstart for the status lifecycle.

Next steps