Sendoso Webhooks

asyncapi: 3.0.0
info:
  title: Sendoso Webhooks
  version: '1.0'
  description: >-
    Sendoso webhooks deliver real-time send status updates. Sendoso does not publish an
    AsyncAPI document; this description was generated by API Evangelist from Sendoso's own
    webhook documentation at https://developer.sendoso.com/webhooks/introduction — every
    event name, payload field, header, retry interval and source IP below is published by
    Sendoso.


    Delivery is powered by Svix: signatures arrive on `svix-id`, `svix-timestamp` and
    `svix-signature`, and the subscription surface is a hosted "webhooks portal" rather than
    an API. There is no webhook-management endpoint — endpoints and event subscriptions are
    configured in the portal by a human.
  contact:
    name: Sendoso Developer Support
    email: developers@sendoso.com
    url: https://developer.sendoso.com/webhooks/introduction
  x-generated-from: documentation
  x-generated-by: API Evangelist enrichment pipeline (local-v1)
  x-generated-on: '2026-08-13'
externalDocs:
  description: Sendoso webhooks documentation
  url: https://developer.sendoso.com/webhooks/introduction
defaultContentType: application/json
servers:
  subscriber:
    host: www.example.com
    protocol: https
    description: >-
      Your endpoint. You supply the URL; Sendoso POSTs to it. Sendoso's own example shape is
      https://www.example.com/sendoso/webhooks/.
channels:
  sendEvents:
    address: /
    title: Send status events
    description: >-
      All send lifecycle events are delivered to the subscribing endpoint. If no event types
      are selected in the portal, the endpoint receives every event regardless of type.
    messages:
      sendStatusChanged:
        $ref: '#/components/messages/sendStatusChanged'
operations:
  receiveSendEvent:
    action: receive
    channel:
      $ref: '#/channels/sendEvents'
    summary: Receive a send status change from Sendoso.
    messages:
      - $ref: '#/channels/sendEvents/messages/sendStatusChanged'
components:
  messages:
    sendStatusChanged:
      name: sendStatusChanged
      title: Send status changed
      contentType: application/json
      description: >-
        Every Sendoso event type carries the same two-field payload. The event type itself is
        not in the body — it is the subscription's type, so the receiver must distinguish
        events by the subscription/delivery metadata, not by the payload.
      headers:
        type: object
        properties:
          svix-id:
            type: string
            description: Unique message id, part of the signed content.
          svix-timestamp:
            type: string
            description: >-
              Attempt timestamp. Messages more than five minutes from current time (past or
              future) are rejected by the verifier.
          svix-signature:
            type: string
            description: >-
              Space-separated list of versioned signatures. Signed content is
              `{svix-id}.{svix-timestamp}.{raw body}`, HMAC-SHA256 with the base64-decoded
              half of the endpoint secret, base64 encoded.
      payload:
        type: object
        required: [send_gid, status_changed_at]
        properties:
          send_gid:
            type: string
            description: The gid of the send.
          status_changed_at:
            type: string
            description: When the send's status changed, in ISO 8601 format.
      tags:
        - name: send.amazon_fulfilling
          description: The Amazon send is being processed.
        - name: send.amazon_shipped
          description: The send has shipped from Amazon and is in transit to Sendoso.
        - name: send.blocked
          description: A request to redeem the send has been blocked.
        - name: send.bounced
          description: The send cannot be redeemed and will be refunded.
        - name: send.canceled
          description: The send has been canceled by the sender.
        - name: send.clicked
          description: The eGift send has been viewed by the recipient.
        - name: send.confirmation_canceled
          description: Address confirmation for a send has been canceled by the sender.
        - name: send.confirming_address
          description: The send is awaiting address confirmation from the recipient.
        - name: send.delivered
          description: The send has been delivered to the recipient.
        - name: send.email_blacklist
          description: A request to redeem the send has been blacklisted.
        - name: send.expired
          description: The link to redeem the send has expired.
        - name: send.failed
          description: The send has failed.
        - name: send.fulfilling
          description: The send is being processed by Sendoso.
        - name: send.fulfillment_issue
          description: There is an issue on the fulfillment side for the send.
        - name: send.initiated
          description: The send is in the process of being created.
        - name: send.insufficient_funds
          description: The send cannot be processed due to insufficient funds.
        - name: send.invalid_email_format
          description: The recipient email in the send is not a valid email.
        - name: send.opened
          description: The eGift send has been opened by the recipient.
        - name: send.order_received
          description: The send order has been received and is being processed.
        - name: send.out_of_stock
          description: The product for the send is out of stock.
        - name: send.pending_approval
          description: The send is pending approval by the sender.
        - name: send.pending_sendoso_approval
          description: The send is pending approval by a Sendoso Admin.
        - name: send.redeemed
          description: The eGift send has been redeemed by the recipient.
        - name: send.refunded
          description: The send has been refunded.
        - name: send.sent
          description: The eGift send has been sent to the recipient.
        - name: send.shipped
          description: The send is in transit to the recipient.
        - name: send.suspicious_email
          description: The recipient email for the send is flagged as suspicious.
        - name: send.undeliverable
          description: The send cannot be delivered to the recipient.
  securitySchemes:
    svixSignature:
      type: httpApiKey
      name: svix-signature
      in: header
      description: >-
        HMAC-SHA256 over `{svix-id}.{svix-timestamp}.{raw body}` using a per-endpoint secret
        (prefix `whsec_`) retrieved from the webhooks portal. Verify the RAW body byte for
        byte — re-serializing the JSON breaks the signature, which Sendoso names as the most
        common integration failure.
x-delivery:
  enablement: >-
    Webhooks must be enabled per organization by Sendoso support; the portal URL is then
    retrieved from the integrations page.
  management_api: false
  retry_schedule:
    - immediately
    - 5s
    - 5m
    - 30m
    - 2h
    - 5h
    - 10h
    - 10h
  retry_note: >-
    Exponential backoff. A message that fails three times before succeeding is delivered
    roughly 35 minutes and 5 seconds after the first attempt.
  response_timeout_seconds: 15
  success_criteria: Any 2xx status is treated as success, regardless of the response payload.
  endpoint_disable_after: 5 days of total failure
  manual_recovery: >-
    The portal supports per-message resend, "Recover Failed Messages" over a time window, and
    replay-all-since-this-time.
  source_ips_us:
    - 44.228.126.217
    - 50.112.21.217
    - 52.24.126.164
    - 54.148.139.208
    - '2600:1f24:64:8000::/52'
  replay_protection: >-
    Timestamps more than five minutes from current time are rejected. Sendoso recommends NTP
    on the receiving server.
x-gaps:
  - >-
    The event type is not carried in the payload, so a single endpoint subscribed to all
    events cannot tell which event it received from the body alone.
  - No AsyncAPI or event schema registry is published by Sendoso.
  - No webhook-management API — subscriptions are portal-only.
  - Source IPs are published for the US only.