WebhooksRegister a webhook
Back to Sofia

Webhooks

Register a webhook

Registers an https URL that Sofia calls with a signed JSON event, retried up to five times on failure. The secret is shown once; 10 webhooks at most.

POSThttps://api.sofia-post.com/api/v1/webhooks
POST/v1/webhooks

This request acts on your real account.

curl -X POST 'https://api.sofia-post.com/api/v1/webhooks' \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://crm.example.com/hooks/sofia","events":["post.published"]}'

Authorizations

  • Authorizationstringrequired

    Your personal key or OAuth access token, sent as Bearer <token>.

Body

application/json

  • urlstringrequired

    The https address Sofia calls. A host that resolves to a private, loopback or link-local address is refused

  • eventsstring[]required

    The events to receive

Response

201application/json

The webhook and its signing secret, shown only once.

  • idstringrequired

    Identifier of the webhook

  • urlstringrequired

    Address called by Sofia

  • eventsstring[]required

    The subscribed events

  • createdAtstring<date-time>required

    When the webhook was registered

  • secretstringrequired

    The HMAC-SHA256 key that signs each delivery (Sofia-Signature). Shown this once only

400

webhook_url_invalid: not https, or a private, loopback or link-local host. webhook_event_invalid: unknown event, or none.

401

The token is missing, unknown, expired or revoked.

403

The token does not have the webhooks:write scope.

409

webhook_limit_reached: already 10 webhooks.

4XXapplication/json

Any other error, in the error envelope.