Sequenzy Webhooks API

openapi: 3.2.0
info:
  title: Sequenzy Webhooks API
  description: Sequenzy API for managing subscribers, tags, events, sequences, and transactional emails
  version: 1.0.0
servers:
- url: https://api.sequenzy.com/api/v1
  description: Production server
- url: https://api.sequenzy.com/v1
  description: Legacy production server alias
security:
- bearerAuth: []
tags:
- name: Webhooks
  description: Configure outbound lifecycle event webhooks
paths:
  /webhooks:
    get:
      operationId: listOutboundWebhooks
      summary: List outbound webhooks
      description: Lists customer-configured outbound webhook endpoints for the authenticated company.
      tags:
      - Webhooks
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  webhooks:
                    type: array
                    items:
                      $ref: '#/components/schemas/OutboundWebhookEndpoint'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
    post:
      operationId: createOutboundWebhook
      summary: Create outbound webhook
      description: Creates an outbound webhook endpoint. The signing secret is returned only in this response.
      tags:
      - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - url
              properties:
                name:
                  type: string
                  example: Production webhook
                url:
                  type: string
                  format: uri
                  example: https://example.com/sequenzy/webhooks
                events:
                  type: array
                  description: Omit to subscribe to default email and SMS lifecycle events plus subscriber.invalid, subscriber.created, and subscriber.unsubscribed. Add campaign.sent, email.opened, email.clicked, email.replied, email.received, subscriber.updated, subscriber.list_subscribed, subscriber.list_unsubscribed, sequence.finished, and sequence.failed explicitly for aggregate campaign completion, engagement, inbound reply, new inbox mail, profile sync, per-list consent sync, or sequence lifecycle events. SMS events (sms.sent, sms.delivered, sms.failed, sms.opted_out) are included in the defaults.
                  items:
                    $ref: '#/components/schemas/OutboundWebhookEventType'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  webhook:
                    $ref: '#/components/schemas/OutboundWebhookEndpoint'
        '400':
          description: Invalid URL or event type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /webhooks/{id}:
    patch:
      operationId: updateOutboundWebhook
      summary: Update outbound webhook
      description: Updates an outbound webhook endpoint URL, name, status, or subscribed events. Changing the URL or enabling the endpoint resets stored endpoint failure state, including `failingSince` and `autoDisabledAt`.
      tags:
      - Webhooks
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                url:
                  type: string
                  format: uri
                status:
                  type: string
                  enum:
                  - enabled
                  - disabled
                events:
                  type: array
                  items:
                    $ref: '#/components/schemas/OutboundWebhookEventType'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  webhook:
                    $ref: '#/components/schemas/OutboundWebhookEndpoint'
        '400':
          description: Invalid update
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteOutboundWebhook
      summary: Delete outbound webhook
      description: Permanently deletes an outbound webhook endpoint along with its delivery history. To keep the endpoint but stop deliveries, use PATCH with status "disabled" instead.
      tags:
      - Webhooks
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  webhook:
                    $ref: '#/components/schemas/OutboundWebhookEndpoint'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
  /webhooks/{id}/secrets:
    post:
      operationId: addOutboundWebhookSigningSecret
      summary: Add outbound webhook signing secret
      description: Adds another active signing secret. Requests are signed once per active secret in the same signature header.
      tags:
      - Webhooks
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Secret added
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  webhook:
                    $ref: '#/components/schemas/OutboundWebhookEndpoint'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /webhooks/{id}/secrets/{secretId}:
    delete:
      operationId: removeOutboundWebhookSigningSecret
      summary: Remove outbound webhook signing secret
      description: Removes an active signing secret. A webhook must keep at least one signing secret.
      tags:
      - Webhooks
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: secretId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Secret removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  webhook:
                    $ref: '#/components/schemas/OutboundWebhookEndpoint'
        '400':
          description: Last signing secret cannot be removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Webhook or signing secret not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
  /webhooks/{id}/test:
    post:
      operationId: testOutboundWebhook
      summary: Send test outbound webhook
      description: Queues a test delivery for a webhook endpoint and resets stored endpoint failure state. The test is delivered to this endpoint even when the endpoint subscribes to no event types, and the queued delivery is returned so you can poll its status without waiting for it to appear in the delivery list.
      tags:
      - Webhooks
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Test delivery queued
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  eventId:
                    type: string
                  queuedDeliveries:
                    type: integer
                  delivery:
                    $ref: '#/components/schemas/OutboundWebhookDelivery'
        '400':
          description: Webhook is disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /webhooks/{id}/deliveries:
    get:
      operationId: listOutboundWebhookDeliveries
      summary: List outbound webhook deliveries
      description: Lists recent delivery attempts for an outbound webhook endpoint.
      tags:
      - Webhooks
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          maximum: 100
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  deliveries:
                    type: array
                    items:
                      $ref: '#/components/schemas/OutboundWebhookDelivery'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
  /webhooks/{id}/deliveries/{deliveryId}/attempts:
    get:
      operationId: listOutboundWebhookDeliveryAttempts
      summary: List outbound webhook delivery attempts
      description: Lists the latest HTTP attempt summary for a webhook delivery.
      tags:
      - Webhooks
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: deliveryId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  attempts:
                    type: array
                    items:
                      $ref: '#/components/schemas/OutboundWebhookDeliveryAttempt'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Webhook or delivery not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
  /webhooks/{id}/deliveries/{deliveryId}/replay:
    post:
      operationId: replayOutboundWebhookDelivery
      summary: Replay outbound webhook delivery
      description: Queues a webhook delivery for another signed POST attempt and resets stored endpoint failure state.
      tags:
      - Webhooks
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: deliveryId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Replay queued
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  delivery:
                    $ref: '#/components/schemas/OutboundWebhookDelivery'
        '400':
          description: Webhook is disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Webhook or delivery not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  headers:
    RetryAfter:
      description: Number of seconds to wait before retrying the request.
      schema:
        type: integer
        minimum: 1
        example: 1
  responses:
    TransientDatabaseUnavailable:
      description: The database was temporarily unavailable. The request may be retried after the delay in Retry-After.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: The service could not reach its database for a moment. Retry the request.
            code: SERVICE_UNAVAILABLE
  schemas:
    OutboundWebhookEndpoint:
      type: object
      properties:
        id:
          type: string
          example: webhook_abc123
        name:
          type: string
          example: Production webhook
        url:
          type: string
          format: uri
          example: https://example.com/sequenzy/webhooks
        status:
          type: string
          enum:
          - enabled
          - disabled
        events:
          type: array
          items:
            $ref: '#/components/schemas/OutboundWebhookEventType'
        consecutiveFailures:
          type: integer
          description: Consecutive failed delivery attempts used for endpoint backoff.
        circuitOpenedAt:
          type:
          - string
          - 'null'
          format: date-time
        circuitOpenUntil:
          type:
          - string
          - 'null'
          format: date-time
        signingSecret:
          type: string
          description: Returned only when creating a webhook or adding a signing secret.
          example: whsec_...
        signingSecrets:
          type: array
          description: Active signing secret metadata. Secret values are returned only once.
          items:
            type: object
            properties:
              id:
                type: string
                example: sec_abc123
              prefix:
                type: string
                example: whsec_abcd12
              createdAt:
                type: string
                format: date-time
        lastSuccessAt:
          type:
          - string
          - 'null'
          format: date-time
        lastFailureAt:
          type:
          - string
          - 'null'
          format: date-time
        failingSince:
          type:
          - string
          - 'null'
          format: date-time
          description: When the current unbroken run of failed deliveries started. `null` once a delivery succeeds.
        autoDisabledAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Set when Sequenzy disabled the endpoint automatically because every delivery failed for 7 days. Cleared when the endpoint is enabled again or its URL changes.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    OutboundWebhookEventType:
      type: string
      enum:
      - email.sent
      - email.delivered
      - email.delivery_delayed
      - email.bounced
      - email.failed
      - email.complained
      - email.opened
      - email.clicked
      - email.replied
      - email.received
      - email.unsubscribed
      - campaign.sent
      - sms.sent
      - sms.delivered
      - sms.failed
      - sms.opted_out
      - subscriber.invalid
      - subscriber.created
      - subscriber.updated
      - subscriber.unsubscribed
      - subscriber.list_subscribed
      - subscriber.list_unsubscribed
      - subscriber_import.completed
      - sequence.finished
      - sequence.failed
      - poll.answered
    OutboundWebhookDeliveryAttempt:
      type: object
      properties:
        id:
          type: string
        attemptNumber:
          type: integer
        status:
          type: string
          enum:
          - succeeded
          - failed
        statusCode:
          type:
          - integer
          - 'null'
        error:
          type:
          - string
          - 'null'
        responseBody:
          type:
          - string
          - 'null'
        durationMs:
          type:
          - integer
          - 'null'
        createdAt:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Error message
        code:
          type: string
          description: Optional stable machine-readable error discriminator when available.
          example: COMPANY_CREATE_REQUIRES_PERSONAL_KEY
        retryable:
          type: boolean
          description: Whether retrying the request can recover from the error.
        issues:
          type: array
          description: Field-level problems with the request, when the endpoint reports them. Up to ten entries; `error` summarizes the first three.
          items:
            $ref: '#/components/schemas/InputIssue'
      required:
      - error
    OutboundWebhookDelivery:
      type: object
      properties:
        id:
          type: string
        eventId:
          type: string
        eventType:
          $ref: '#/components/schemas/OutboundWebhookEventType'
        status:
          type: string
          enum:
          - pending
          - delivering
          - succeeded
          - failed
          - skipped
        attempts:
          type: integer
        queuedAt:
          type:
          - string
          - 'null'
          format: date-time
        lastStatusCode:
          type:
          - integer
          - 'null'
        lastError:
          type:
          - string
          - 'null'
        lastResponseBody:
          type:
          - string
          - 'null'
        nextAttemptAt:
          type:
          - string
          - 'null'
          format: date-time
        lastAttemptAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    InputIssue:
      type: object
      properties:
        path:
          type: string
          description: Dotted field path, such as `audience.subscriberIds[0]`. Empty when the problem is with the request body itself.
          example: kind
        message:
          type: string
          description: What is wrong with the field.
          example: must be "add_tags"
        allowedValues:
          type: array
          description: Accepted values when the field only takes a fixed set of values.
          items: {}
          example:
          - add_tags
      required:
      - path
      - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token