Outpost Webhooks API

openapi: 3.2.0
info:
  title: Outpost Ai Webhooks API
  version: 0.1.0
  description: 'Operations tagged Webhooks across 2 of this provider''s published API definitions: outpost-ai-stripe-mor.yaml, stripe-billing-mor.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.outpostanywhere.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Webhooks
  description: Events Outpost posts to the merchant during renewal cycles.
paths: {}
webhooks:
  payment.succeeded:
    post:
      tags:
      - Webhooks
      summary: Renewal payment succeeded
      description: 'Posted by Outpost to your webhook URL after a successful

        off-session renewal payment. On receipt, the merchant should:


        1. Verify the `Mor-Signature` header (HMAC-SHA256 over `t.payload`,

        keyed with the shared webhook secret).

        2. Call Stripe `POST /v1/payment_records/report_payment` on your

        account with `outcome=guaranteed` and

        `processor_details.custom.payment_reference = processor_charge_id`.

        3. Call Stripe `POST /v1/invoices/{merchant_invoice_id}/attach_payment`

        with the new PaymentRecord — the invoice transitions to `paid`.


        Use deterministic idempotency keys on Stripe (e.g.

        `prpt_{merchant_invoice_id}_{payment_id}`) so retries are safe.'
      parameters:
      - $ref: '#/components/parameters/MorSignature'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutboundEvent'
            example:
              id: evt_a1b2c3d4
              type: payment.succeeded
              created: 1747051200
              data:
                object:
                  payment_id: pay_a1b2c3
                  merchant_invoice_id: in_1QzABC
                  merchant_customer_id: cus_QmerchantSide
                  processor_charge_id: ch_3QzABC
                  processor_payment_intent_id: pi_3QzABC
                  amount: 1990
                  currency: BRL
                  status: succeeded
      responses:
        '200':
          description: Acknowledged. Outpost will not retry.
        4XX:
          description: Outpost gives up after 4xx (treat as permanent failure).
        5XX:
          description: Outpost retries with exponential backoff.
    servers:
    - url: https://api.outpostanywhere.com
      description: Production
  payment.failed:
    post:
      tags:
      - Webhooks
      summary: Renewal payment failed
      description: 'Posted when the off-session PaymentIntent on Outpost''s PSP account

        ends in `failed`. Leave the merchant invoice open — Stripe Billing''s

        Smart Retries will trigger another `invoice.created` on the next attempt,

        which Outpost will pick up and try again.'
      parameters:
      - $ref: '#/components/parameters/MorSignature'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutboundEvent'
            example:
              id: evt_failed1
              type: payment.failed
              created: 1747051200
              data:
                object:
                  payment_id: pay_b2c3d4
                  merchant_invoice_id: in_1QzABC
                  merchant_customer_id: cus_QmerchantSide
                  processor_charge_id: ''
                  processor_payment_intent_id: pi_3QzABC
                  amount: 1990
                  currency: BRL
                  status: failed
                  failure_message: Your card was declined.
                  decline_code: insufficient_funds
      responses:
        '200':
          description: Acknowledged. Outpost will not retry.
        4XX:
          description: Outpost gives up after 4xx (treat as permanent failure).
        5XX:
          description: Outpost retries with exponential backoff.
    servers:
    - url: https://api.outpostanywhere.com
      description: Production
  payment.requires_action:
    post:
      tags:
      - Webhooks
      summary: Renewal payment requires customer action
      description: 'Posted when the renewal PaymentIntent requires SCA / 3DS or other

        customer-side action. As with `payment.failed`, leave the invoice open

        and let Stripe Billing''s dunning surface the action to the customer.'
      parameters:
      - $ref: '#/components/parameters/MorSignature'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutboundEvent'
            example:
              id: evt_action1
              type: payment.requires_action
              created: 1747051200
              data:
                object:
                  payment_id: pay_c3d4e5
                  merchant_invoice_id: in_1QzABC
                  merchant_customer_id: cus_QmerchantSide
                  processor_charge_id: ''
                  processor_payment_intent_id: pi_3QzABC
                  amount: 1990
                  currency: BRL
                  status: requires_action
                  failure_message: Authentication required.
                  decline_code: authentication_required
      responses:
        '200':
          description: Acknowledged. Outpost will not retry.
        4XX:
          description: Outpost gives up after 4xx (treat as permanent failure).
        5XX:
          description: Outpost retries with exponential backoff.
    servers:
    - url: https://api.outpostanywhere.com
      description: Production
  payment.refunded:
    post:
      tags:
      - Webhooks
      summary: Payment refunded — full or partial
      description: 'Fired after every successful refund. Inspect

        `amount_refunded_total` to decide whether the payment is now fully

        or partially refunded, and call

        `POST /v1/payment_records/report_refund` on your Stripe account to

        keep the corresponding PaymentRecord in sync.'
      parameters:
      - $ref: '#/components/parameters/MorSignature'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutboundEvent'
            example:
              id: evt_refund1
              type: payment.refunded
              created: 1747051200
              data:
                object:
                  payment_id: pay_a1b2c3
                  merchant_invoice_id: in_1QzABC
                  merchant_customer_id: cus_QmerchantSide
                  refund_id: rfnd_a1b2c3d4e5f6789
                  amount: 990
                  amount_refunded_total: 990
                  currency: BRL
                  status: partially_refunded
                  reason: requested_by_customer
                  processor_refund_id: re_3QzABC
      responses:
        '200':
          description: Acknowledged. Outpost will not retry.
        4XX:
          description: Outpost gives up after 4xx (treat as permanent failure).
        5XX:
          description: Outpost retries with exponential backoff.
    servers:
    - url: https://api.outpostanywhere.com
      description: Production
components:
  parameters:
    MorSignature:
      name: Mor-Signature
      in: header
      required: true
      description: '`t=<unix_seconds>,v1=<hex_hmac_sha256>` where the HMAC is computed over

        the byte string `"<t>.<raw_request_body>"` using the shared webhook

        secret as the key. Reject requests where `t` is too old (5 min

        tolerance recommended) or the signature doesn''t match.

        '
      schema:
        type: string
        examples:
        - t=1747051200,v1=9b8a7c6d5e4f...
  schemas:
    OutboundPaymentObject:
      type: object
      description: 'Common payload shape for all `payment.*` webhook events. Some fields

        are only present on certain event types — see field-level notes.

        '
      required:
      - payment_id
      - amount
      - currency
      - status
      properties:
        payment_id:
          type: string
          description: Outpost-owned payment identifier (`pay_…`).
        merchant_invoice_id:
          type: string
          description: 'The Stripe Invoice ID **on your account** that triggered

            this renewal. Pass to `attach_payment` after `report_payment`.

            Present on all `payment.*` events tied to a Stripe Billing

            renewal cycle.

            '
        merchant_customer_id:
          type: string
          description: Customer ID on your Stripe account.
        processor_charge_id:
          type: string
          description: 'Charge ID on Outpost''s PSP account when present. Used as

            `payment_reference` on `payment_records/report_payment`. Empty on

            `failed` / `requires_action`. Not present on `payment.refunded`

            events (see `processor_refund_id` instead).

            '
        processor_payment_intent_id:
          type: string
          description: PaymentIntent ID on Outpost's PSP account.
        amount:
          type: integer
          description: 'For `payment.succeeded` / `failed` / `requires_action`, the

            payment amount. For `payment.refunded`, the amount refunded by

            this specific event.

            '
        amount_refunded_total:
          type: integer
          description: 'Cumulative amount refunded across all refunds on this payment.

            Only present on `payment.refunded` events. When equal to the

            original payment amount the payment is fully refunded; otherwise

            partially refunded (see `status`).

            '
        currency:
          type: string
        status:
          type: string
          enum:
          - succeeded
          - failed
          - requires_action
          - refunded
          - partially_refunded
        refund_id:
          type: string
          description: 'Outpost-owned refund identifier. Only present on

            `payment.refunded` events.

            '
        processor_refund_id:
          type: string
          description: 'Refund ID on Outpost''s PSP account. Only present on

            `payment.refunded` events.

            '
        reason:
          type: string
          description: 'Refund reason as supplied on the request. Only present on

            `payment.refunded` events.

            '
        failure_message:
          type: string
          description: Human-readable decline reason (present on `failed` / `requires_action`).
        decline_code:
          type: string
          description: PSP decline code (present on `failed` / `requires_action`).
    OutboundEvent:
      type: object
      required:
      - id
      - type
      - created
      - data
      properties:
        id:
          type: string
          description: Outpost event ID. Use it to dedupe.
          examples:
          - evt_a1b2c3d4
        type:
          type: string
          enum:
          - payment.succeeded
          - payment.failed
          - payment.requires_action
          - payment.refunded
        created:
          type: integer
          description: Unix seconds.
        data:
          type: object
          required:
          - object
          properties:
            object:
              $ref: '#/components/schemas/OutboundPaymentObject'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Obtain via `POST /oauth/token` with the `client_credentials` grant.

        Send as `Authorization: Bearer <access_token>` on every Outpost API

        endpoint.

        '
x-refined-from:
- outpost-ai-stripe-mor.yaml
- stripe-billing-mor.yaml