Orb Automation webhooks API

openapi: 3.2.0
info:
  title: Reference Automation webhooks API
  description: 'Orb''s API is built with the following principles in mind:


    1. **Predictable developer experience**: Where applicable, the Orb API uses industry-standard patterns such as

    cursor-based pagination and standardized error output. To help with debugging in critical API

    actions, the API always strives to provide detailed and actionable error messages. Aliases

    such as external customer IDs aid in fast integration times.

    2. **Reliably real time**: Orb''s event-based APIs, such as event ingestion are designed to handle extremely high

    throughput and scale with concurrent load. Orb also provides a real-time event-level credits

    ledger and a highly performant webhooks architecture.

    3. **Flexibility at the forefront**: Features like timezone localization and the ability to amend historical usage

    show the flexible nature of the platform.


    You can download the latest OpenAPI spec here - pass `?version=3.0` for an

    OpenAPI 3.0-compatible spec.'
  contact:
    name: Orb, Inc.
    url: https://www.withorb.com/
    email: team@withorb.com
  version: '1.0'
servers:
- url: https://api.withorb.com/v1
  description: Production server
security:
- APIKeyAuth: []
tags:
- name: Automation webhooks
  description: Payloads Orb delivers for automation events. Endpoint configuration, retries and signature verification are covered in the webhooks guide.
paths: {}
webhooks:
  invoice.automation_schedule_step_executed:
    post:
      tags:
      - Automation webhooks
      summary: invoice.automation_schedule_step_executed
      description: Issued when a collections-automation schedule step is executed for an invoice.
      parameters:
      - description: '`v1=` followed by the hex HMAC-SHA256 of `v1:{X-Orb-Timestamp}:{raw request body}`, keyed by the endpoint''s webhook secret. The header may carry several space-separated signatures during a secret rotation; a receiver accepts the delivery when any `v1` signature matches. Compare in constant time, and sign the bytes as received rather than a re-serialized body.'
        required: true
        schema:
          type: string
        name: X-Orb-Signature
        in: header
      - description: When the delivery was signed, ISO 8601 to milliseconds. It is part of the signed message, so a receiver must reject timestamps outside its tolerance to stop replays.
        required: true
        schema:
          type: string
          format: date-time
        name: X-Orb-Timestamp
        in: header
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceAutomationScheduleStepExecutedWebhookEventMessage'
        required: true
      responses:
        2XX:
          description: Any 2xx acknowledges receipt.
      security: []
      x-hidden: true
      x-mint:
        metadata:
          sidebarTitle: invoice.automation_schedule_step_executed
          title: Invoice automation schedule step executed
          authMethod: none
components:
  schemas:
    AutomationWebhookInvoice:
      properties:
        id:
          type: string
          title: Id
        customer_id:
          type: string
          title: Customer Id
        customer_name:
          type: string
          title: Customer Name
        external_customer_id:
          oneOf:
          - type: string
          - type: 'null'
          title: External Customer Id
        subscription_id:
          oneOf:
          - type: string
          - type: 'null'
          title: Subscription Id
        invoice_number:
          type: string
          title: Invoice Number
        status:
          type: string
          title: Status
        amount_due:
          type: string
          title: Amount Due
        currency:
          type: string
          title: Currency
        issued_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Issued At
        invoice_date:
          type: string
          format: date-time
          title: Invoice Date
        due_date:
          oneOf:
          - type: string
            format: date
          - type: 'null'
          title: Due Date
        memo:
          oneOf:
          - type: string
          - type: 'null'
          title: Memo
        hosted_invoice_url:
          oneOf:
          - type: string
          - type: 'null'
          title: Hosted Invoice Url
        payment_method_last_four_digits:
          oneOf:
          - type: string
          - type: 'null'
          title: Payment Method Last Four Digits
      type: object
      required:
      - id
      - customer_id
      - customer_name
      - external_customer_id
      - subscription_id
      - invoice_number
      - status
      - amount_due
      - currency
      - issued_at
      - invoice_date
      - due_date
      - memo
      - hosted_invoice_url
      - payment_method_last_four_digits
      title: AutomationWebhookInvoice
      description: 'The invoice fields a consumer needs to run their own notification flows without a

        follow-up API call, mirroring the variables Orb''s own automation emails render against.'
    InvoiceAutomationScheduleStepExecutedWebhookEventMessage:
      properties:
        id:
          type: string
          description: The ID of this webhook event.
        created_at:
          type: string
          format: date-time
          description: The time at which this event was created, to the second.
        type:
          type: string
          enum:
          - invoice.automation_schedule_step_executed
          description: The event this payload describes.
        payload_style:
          type: string
          enum:
          - expanded
          - standard
          description: The serialization style this payload was rendered in, as configured on the endpoint.
        invoice:
          $ref: '#/components/schemas/AutomationWebhookInvoice'
        properties:
          $ref: '#/components/schemas/InvoiceAutomationScheduleStepExecutedWebhookEventProperties'
      type: object
      required:
      - id
      - created_at
      - type
      - payload_style
      - invoice
      - properties
      title: InvoiceAutomationScheduleStepExecutedWebhookEventMessage
      description: Issued when a collections-automation schedule step is executed for an invoice.
      x-orb-webhook-event: invoice.automation_schedule_step_executed
    RetryPaymentActionEntry:
      properties:
        action_type:
          type: string
          enum:
          - retry_payment
          title: Action Type
          default: retry_payment
        payment_transaction_record_id:
          oneOf:
          - type: string
          - type: 'null'
          title: Payment Transaction Record Id
        payment_provider:
          oneOf:
          - type: string
          - type: 'null'
          title: Payment Provider
        payment_provider_transaction_id:
          oneOf:
          - type: string
          - type: 'null'
          title: Payment Provider Transaction Id
        amount_attempted:
          oneOf:
          - type: string
          - type: 'null'
          title: Amount Attempted
        currency:
          oneOf:
          - type: string
          - type: 'null'
          title: Currency
        outcome:
          type: string
          enum:
          - succeeded
          - failed
          - skipped
          title: Outcome
        failure_reason:
          oneOf:
          - type: string
          - type: 'null'
          title: Failure Reason
      type: object
      required:
      - payment_transaction_record_id
      - payment_provider
      - payment_provider_transaction_id
      - amount_attempted
      - currency
      - outcome
      - failure_reason
      title: RetryPaymentActionEntry
    SendEmailActionEntry:
      properties:
        action_type:
          type: string
          enum:
          - send_email
          title: Action Type
          default: send_email
        recipient:
          oneOf:
          - type: string
          - type: 'null'
          title: Recipient
        sent:
          type: boolean
          title: Sent
      type: object
      required:
      - recipient
      - sent
      title: SendEmailActionEntry
    InvoiceAutomationScheduleStepExecutedWebhookEventProperties:
      properties:
        automation_schedule_template_id:
          oneOf:
          - type: string
          - type: 'null'
          title: Automation Schedule Template Id
        automation_schedule_template_name:
          oneOf:
          - type: string
          - type: 'null'
          title: Automation Schedule Template Name
        step_id:
          type: string
          title: Step Id
        label:
          type: string
          title: Label
        scheduled_at:
          type: string
          format: date-time
          title: Scheduled At
        executed_at:
          type: string
          format: date-time
          title: Executed At
        actions:
          items:
            oneOf:
            - $ref: '#/components/schemas/SendEmailActionEntry'
            - $ref: '#/components/schemas/RetryPaymentActionEntry'
            discriminator:
              propertyName: action_type
              mapping:
                retry_payment: '#/components/schemas/RetryPaymentActionEntry'
                send_email: '#/components/schemas/SendEmailActionEntry'
          type: array
          title: Actions
      type: object
      required:
      - automation_schedule_template_id
      - automation_schedule_template_name
      - step_id
      - label
      - scheduled_at
      - executed_at
      - actions
      title: InvoiceAutomationScheduleStepExecutedWebhookEventProperties
  securitySchemes:
    APIKeyAuth:
      type: http
      description: API Keys can be issued in the Orb's web application.
      scheme: bearer