Skip to main content
When you create a response with POST /v1/responses or the Messages API, you can provide a completion webhook in the request metadata. When the response reaches a completed state, 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="sail-default",
    input="Summarize this document.",
    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.

​
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="sail-default",
    input="Summarize this document.",
    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

  • 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.