Webhooks

Receive completion notifications via completion_webhook and webhook_token

When you create a request through POST /v1/responses, POST /v1/chat/completions, or POST /v1/messages, you can provide a completion webhook in request metadata. When processing finishes, Sail will POST the full response payload to your URL so you can process it without polling.

Enabling a completion webhook

Include a completion_webhook URL in the metadata object of your create request. The URL must be http or https.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_SAIL_API_KEY",
    base_url="https://api.sailresearch.com/v1",
)

response = client.responses.create(
    model="zai-org/GLM-5.2-FP8",
    input="Summarize this document.",
    background=True,
    metadata={
        "completion_webhook": "https://your-server.com/sail-completion",
    },
)

If metadata.completion_webhook is omitted or invalid, no webhook request is sent. The create call and the response itself are unchanged; webhooks are optional and best-effort.

For Chat Completions and Anthropic Messages, pass the same metadata keys (completion_webhook, webhook_token) on the request body.

Webhook payload

Sail sends a POST request to your URL with:

• Content-Type: application/json
• Body: The same JSON object returned by GET /v1/responses/{response_id}

Securing webhooks with a token

To verify that incoming requests are from Sail, set webhook_token in the metadata. Sail will send the value of webhook_token as a Bearer token in the Authorization header of the webhook POST.

response = client.responses.create(
    model="zai-org/GLM-5.2-FP8",
    input="Summarize this document.",
    background=True,
    metadata={
        "completion_webhook": "https://your-server.com/sail-completion",
        "webhook_token": "your-secret-token",
    },
)

Your server can check Authorization: Bearer your-secret-token and reject requests that don’t match.

Delivery behavior

• Duplicates: Sail may occasionally deliver the same webhook more than once. Log the response id from the webhook body and ignore events you have already processed.
• Retries: Sail retries failed delivery up to 3 times (e.g. non-2xx status or network errors). Respond with a 2xx status as soon as you have accepted the payload so that Sail stops retrying.
• Timeout: Each attempt has a 30-second timeout. If the request times out or fails, the next attempt is made.
• Best-effort: Webhook failures are logged but do not affect the response or the API. The response remains available via GET /v1/responses/{response_id} even if the webhook never succeeds.

Full example

Here’s a full, end-to-end example using ngrok:

1. Start a local webhook listener that prints the payload and returns 200:

python -c "
from http.server import HTTPServer, BaseHTTPRequestHandler; import json
class H(BaseHTTPRequestHandler):
 def do_POST(self):
  print(json.dumps(json.loads(self.rfile.read(int(self.headers['Content-Length']))), indent=2))
  self.send_response(200); self.end_headers()
HTTPServer(('127.0.0.1', 8765), H).serve_forever()
"

2. In a second terminal, expose it with ngrok:

ngrok http 8765

Copy the https://xxxx.ngrok-free.app forwarding URL from the output.

3. In a third terminal, create a response with the webhook:

curl -X POST https://api.sailresearch.com/v1/responses \
  -H "Authorization: Bearer YOUR_SAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zai-org/GLM-5.2-FP8",
    "input": "What is 2+2? Reply with just the number.",
    "background": true,
    "metadata": {
      "completion_webhook": "https://xxxx.ngrok-free.app"
    }
  }'

When the response completes, Sail POSTs the full payload to your listener.