Webhooks

Instead of polling, configure webhooks to receive results automatically. Provide Further AI with your webhook URL(s), authentication method, credentials if needed, and preferred response format.

Setup

To enable webhooks, provide the following to your Further AI representative:

1. Webhook URL(s) — your HTTPS endpoint(s)
2. Authentication method — none, oauth2, or api_key
3. Credentials — if using OAuth2 or API key auth
4. Response format — url or inline

Authentication Types

Response Format

The response format controls how step data is delivered in webhook payloads.

URL Mode Step Data

Each step contains a signed URL to download the data:

1
{
2
  "step_name": "extraction_step",
3
  "data": {
4
    "url": "https://storage.blob.core.windows.net/.../extraction_step_data.json?sv=...&se=..."
5
  }
6
}

Inline Mode Step Data

Each step contains the full data embedded directly:

1
{
2
  "step_name": "extraction_step",
3
  "data": {
4
    "schema": { ... },
5
    "data": [
6
      {
7
        "field_name": {
8
          "value": "extracted value",
9
          "confidence_score": 0.95
10
        }
11
      }
12
    ],
13
    "metadata": { ... }
14
  }
15
}

Success Webhook Payload

Sent via POST to your webhook URL(s) when a workflow execution completes:

1
{
2
  "workflow_id": "d5929cd9-1d50-49ea-afb4-b5ce43c1296a",
3
  "workflow_execution_id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
4
  "status": "completed",
5
  "metadata": {"external_id": "123"},
6
  "steps": [
7
    {
8
      "step_name": "extraction_step",
9
      "data": { }
10
    }
11
  ]
12
}

The steps[].data structure depends on the response format — either a download URL or inline data as shown above.

Failure Webhook Payload

1
{
2
  "workflow_execution_id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
3
  "status": "failed",
4
  "metadata": {"external_id": "123"},
5
  "error_message": "Description of what went wrong"
6
}

Inline Payload Too Large

When using inline mode, if the payload exceeds the configured size limit (default: 1 MB):

1
{
2
  "status": "completed",
3
  "steps": [],
4
  "error": "inline_payload_too_large",
5
  "size_bytes": 1500000,
6
  "limit_bytes": 1000000
7
}

Retry Behavior

If your webhook endpoint does not return a 2xx status code, Further AI retries delivery:

Retry policy by error type:

• Network / transient failures — retried with exponential backoff
• 401/403 (OAuth2) — automatic token refresh, then retry
• Other 4xx errors — not retried (permanent client error)
• 5xx errors — retried with exponential backoff

Best Practices

• Return 2xx quickly — acknowledge the webhook immediately and process data asynchronously
• Handle duplicates — in rare cases a webhook may be delivered more than once; use workflow_execution_id to deduplicate
• Use HTTPS — HTTP URLs are not supported
• Log payloads — for debugging and auditing