sangtao.ai
API key

Webhooks

Create an endpoint

Register a URL to get events. Answers with its signing secret, once.

POSThttps://api.sangtao.ai/v2/webhooks

Authorization

  • X-Api-Keystring · headerrequired

    Your API key, from the API keys page of your account.

Events, the signature and retries: Webhook.

Body

  • urlstringrequired

    A public https URL on port 443, without a user or password in it. Up to 500 characters

  • eventsstring[]required

    The event types to get, or ["*"] for all

    Available options:*image.completedimage.failedvideo.completedvideo.failedpost.publishedpost.failedsocial_account.needs_attention

  • descriptionstring

    A note for yourself. Up to 200 characters

Response

  • idstringrequired

    The endpoint’s id, whk_…

  • urlstringrequired

    Where events are sent

  • eventsstring[]required

    The event types it gets. ["*"] is all of them

  • descriptionstring | null

    Your note

  • enabledbooleanrequired

    Whether events are sent to it

  • statusstringrequired

    disabled_failing: turned off after 3 days of failed deliveries

    Available options:activedisableddisabled_failing

  • createdAtstringrequired

    When it was created (ISO 8601, UTC). It only gets events from then on

  • lastDeliveryAtstring | null

    Last attempt to deliver to it

  • lastSuccessAtstring | null

    Last delivery it answered with 2xx

  • lastFailureAtstring | null

    Last failed attempt

  • secretstringrequired

    whsec_… — shown only in this answer. Store it: it signs every delivery

The secret is shown once. Lost it? Rotate it.

Errors

StatuserrorCodeWhen
422INVALID_WEBHOOK_URLurl is not a public https URL on port 443, or carries a user or password
422INVALID_WEBHOOK_EVENTevents is empty or has an unknown type — the allowed ones in details[0].params.allowed
422VALIDATION_ERRORdescription is over 200 characters
422WEBHOOK_LIMIT_REACHEDYou already have 10 endpoints
POST/webhooks
curl -X POST "https://api.sangtao.ai/v2/webhooks" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/sangtao",
    "events": [
      "image.completed",
      "image.failed"
    ],
    "description": "Production"
  }'
{
  "success": true,
  "data": {
    "id": "whk_4nP8rT2xK",
    "url": "https://example.com/webhooks/sangtao",
    "events": [
      "image.completed",
      "image.failed"
    ],
    "description": "Production",
    "enabled": true,
    "status": "active",
    "createdAt": "2026-11-10T08:00:00Z",
    "lastDeliveryAt": null,
    "lastSuccessAt": null,
    "lastFailureAt": null,
    "secret": "whsec_Zx3…"
  }
}