asyncapi: 3.0.0
info:
  title: Confido Legal Webhooks
  version: 1.0.0
  description: 'AsyncAPI description of the Confido Legal webhook surface, generated by API Evangelist

    from the provider''s published webhook documentation. Confido Legal does not publish an

    AsyncAPI document of its own; every event name, payload field, header, signature

    algorithm and retry interval below is taken verbatim from

    https://docs.confidolegal.com/docs/webhooks/configure and

    https://docs.confidolegal.com/docs/webhooks/webhook-types.


    Confido POSTs an ARRAY of minimal payloads to the registered URL. Each payload carries

    identifiers only — the consumer then queries the GraphQL API for current state.

    '
  contact:
    name: Confido Legal Support
    email: support@confidolegal.com
    url: https://confidolegal.com/contact
  externalDocs:
    url: https://docs.confidolegal.com/docs/webhooks/configure
x-provenance:
  generated: '2026-09-05'
  method: generated
  source: https://docs.confidolegal.com/docs/webhooks/webhook-types
  note: Generated from documentation, not harvested. Confido publishes no AsyncAPI file; probed /asyncapi.yaml
    and /asyncapi.json on docs.confidolegal.com and api.gravity-legal.com, both absent.
defaultContentType: application/json
servers:
  subscriber:
    host: your-application.example.com
    protocol: https
    description: The webhook URL YOU register in the Confido Legal Partner Portal under Settings > Webhooks,
      or with the webhookUrlCreate mutation. Confido is the publisher; your endpoint is the server that
      receives the POST.
channels:
  webhookEndpoint:
    address: /
    title: Registered webhook endpoint
    description: A single HTTPS endpoint receives every selected event type. The request body is an ARRAY
      of event payloads, not a single object. You receive nothing for types you have not selected in the
      portal.
    messages:
      DisbursementUpdated:
        $ref: '#/components/messages/DisbursementUpdated'
      FirmUpdated:
        $ref: '#/components/messages/FirmUpdated'
      StatementCreated:
        $ref: '#/components/messages/StatementCreated'
      StatementUpdated:
        $ref: '#/components/messages/StatementUpdated'
      StoredPaymentMethodCreated:
        $ref: '#/components/messages/StoredPaymentMethodCreated'
      StoredPaymentMethodUpdated:
        $ref: '#/components/messages/StoredPaymentMethodUpdated'
      StoredPaymentMethodDeleted:
        $ref: '#/components/messages/StoredPaymentMethodDeleted'
      StoredDisbursementMethodCreated:
        $ref: '#/components/messages/StoredDisbursementMethodCreated'
      StoredDisbursementMethodUpdated:
        $ref: '#/components/messages/StoredDisbursementMethodUpdated'
      StoredDisbursementMethodDeleted:
        $ref: '#/components/messages/StoredDisbursementMethodDeleted'
      TransactionCreated:
        $ref: '#/components/messages/TransactionCreated'
      TransactionFundsInTransit:
        $ref: '#/components/messages/TransactionFundsInTransit'
      TransactionDeposited:
        $ref: '#/components/messages/TransactionDeposited'
      TransactionVoided:
        $ref: '#/components/messages/TransactionVoided'
      TransactionRefunded:
        $ref: '#/components/messages/TransactionRefunded'
      TransactionPartiallyRefunded:
        $ref: '#/components/messages/TransactionPartiallyRefunded'
      TransactionAchReturned:
        $ref: '#/components/messages/TransactionAchReturned'
operations:
  receiveWebhook:
    action: receive
    channel:
      $ref: '#/channels/webhookEndpoint'
    title: Receive a Confido Legal webhook batch
    description: Verify the X-SIGNATURE HMAC-SHA512 header, deduplicate on eventId, and respond 2xx within
      5 seconds. Non-2xx or slower puts the event into the retry ladder (5 min, 20 min, 60 min, 1 day,
      dead letter). If an event dead-letters and the URL has had no successful response in 24 hours, Confido
      DISABLES the URL and it must be re-enabled in the Partner Portal.
    messages:
    - $ref: '#/channels/webhookEndpoint/messages/TransactionCreated'
    - $ref: '#/channels/webhookEndpoint/messages/DisbursementUpdated'
    - $ref: '#/channels/webhookEndpoint/messages/FirmUpdated'
components:
  schemas:
    EventEnvelope:
      type: object
      required:
      - data
      - type
      - firmId
      - eventId
      properties:
        data:
          type: object
          description: The specific data for this webhook type. Shape varies by event type.
        type:
          type: string
          description: The event type, e.g. transaction.created.
        firmId:
          type: string
          description: The id of the Firm this event is associated with.
        eventId:
          type: string
          description: Unique id for this event. USE IT AS YOUR IDEMPOTENCY KEY — manual resends reuse
            the same eventId, so a handler keyed on it is safe against retries and replays.
    IdRef:
      type: object
      required:
      - id
      properties:
        id:
          type: string
    DisbursementSnapshot:
      type: object
      description: Documented snapshot fields carried on disbursement.updated.
      properties:
        id:
          type: string
        allowedMethods:
          type: array
          items:
            type: string
            description: DisbursementMethod enum
        amount:
          type: integer
          description: Amount in cents.
        authorizedIdentities:
          type: array
          items:
            type: object
        clientId:
          type:
          - string
          - 'null'
        fundingAccountId:
          type: string
        matterId:
          type:
          - string
          - 'null'
        metadata:
          type:
          - object
          - 'null'
        publicKey:
          type:
          - string
          - 'null'
        status:
          type: string
          description: DisbursementStatus enum
  messageTraits:
    ConfidoWebhook:
      headers:
        type: object
        required:
        - X-SIGNATURE
        properties:
          X-SIGNATURE:
            type: string
            description: Base64-encoded HMAC-SHA512 of the JSON-serialized payload, keyed with the webhook
              secret from the Partner Portal. Verify before processing.
      bindings:
        http:
          method: POST
  messages:
    TransactionCreated:
      name: transaction.created
      title: Transaction created
      summary: Sent when a new Transaction is created.
      traits:
      - $ref: '#/components/messageTraits/ConfidoWebhook'
      payload:
        type: object
        allOf:
        - $ref: '#/components/schemas/EventEnvelope'
        properties:
          data:
            type: object
            properties:
              transaction:
                type: object
                description: Documented typing for this event is richer than the id-only shape used by
                  the other transaction events. Full typing is browsable in the sandbox playground under
                  root > Query > transaction.
                properties:
                  id:
                    type: string
                  achReturnCode:
                    type:
                    - string
                    - 'null'
                  achReturnReason:
                    type:
                    - string
                    - 'null'
                  aggregatePaymentLink:
                    $ref: '#/components/schemas/IdRef'
                  amountProcessed:
                    type: number
                  amountRefunded:
                    type: number
                  bankAccount:
                    $ref: '#/components/schemas/IdRef'
                  cardBrand:
                    type:
                    - string
                    - 'null'
                  client:
                    $ref: '#/components/schemas/IdRef'
                  createdOn:
                    type: string
                    format: date-time
                  disbursement:
                    $ref: '#/components/schemas/IdRef'
                  disbursementAmounts:
                    type:
                    - object
                    - 'null'
                  errorMessage:
                    type:
                    - string
                    - 'null'
                  firm:
                    $ref: '#/components/schemas/IdRef'
                  lastFour:
                    type:
                    - string
                    - 'null'
                  matter:
                    $ref: '#/components/schemas/IdRef'
                  payerEmail:
                    type:
                    - string
                    - 'null'
                  payerName:
                    type:
                    - string
                    - 'null'
                  payerNotes:
                    type:
                    - string
                    - 'null'
                  paymentMethod:
                    type: string
                    description: TransactionPaymentMethod enum
                  payment:
                    $ref: '#/components/schemas/IdRef'
                  paymentLink:
                    $ref: '#/components/schemas/IdRef'
                  settledOn:
                    type:
                    - string
                    - 'null'
                    format: date-time
                  standingLink:
                    $ref: '#/components/schemas/IdRef'
                  status_v2:
                    type: string
                    description: TransactionStatus2 enum
                  storedPaymentMethod:
                    $ref: '#/components/schemas/IdRef'
                  subscription:
                    $ref: '#/components/schemas/IdRef'
                  type:
                    type: string
                    description: TransactionType enum
    TransactionFundsInTransit:
      name: transaction.funds_in_transit
      summary: Sent when a Transaction moves to FUNDS_IN_TRANSIT.
      traits:
      - $ref: '#/components/messageTraits/ConfidoWebhook'
      payload:
        $ref: '#/components/schemas/EventEnvelope'
    TransactionDeposited:
      name: transaction.deposited
      summary: Sent when a Transaction is deposited in the Firm's account.
      traits:
      - $ref: '#/components/messageTraits/ConfidoWebhook'
      payload:
        $ref: '#/components/schemas/EventEnvelope'
    TransactionVoided:
      name: transaction.voided
      summary: Sent when a Transaction is voided.
      traits:
      - $ref: '#/components/messageTraits/ConfidoWebhook'
      payload:
        $ref: '#/components/schemas/EventEnvelope'
    TransactionRefunded:
      name: transaction.refunded
      summary: Sent when a Transaction is fully refunded.
      traits:
      - $ref: '#/components/messageTraits/ConfidoWebhook'
      payload:
        $ref: '#/components/schemas/EventEnvelope'
    TransactionPartiallyRefunded:
      name: transaction.partially_refunded
      summary: Sent when a Transaction is partially refunded.
      traits:
      - $ref: '#/components/messageTraits/ConfidoWebhook'
      payload:
        $ref: '#/components/schemas/EventEnvelope'
    TransactionAchReturned:
      name: transaction.ach_returned
      summary: Sent when a settled ACH payment is returned by the bank and funds are reversed. Partial
        returns do not exist.
      traits:
      - $ref: '#/components/messageTraits/ConfidoWebhook'
      payload:
        $ref: '#/components/schemas/EventEnvelope'
    DisbursementUpdated:
      name: disbursement.updated
      summary: Sent when a disbursement is updated. Uniquely among Confido events the payload carries
        BOTH disbursement and oldDisbursement, so the consumer can diff the transition rather than re-query.
      traits:
      - $ref: '#/components/messageTraits/ConfidoWebhook'
      payload:
        type: object
        allOf:
        - $ref: '#/components/schemas/EventEnvelope'
        properties:
          data:
            type: object
            properties:
              disbursement:
                $ref: '#/components/schemas/DisbursementSnapshot'
              oldDisbursement:
                $ref: '#/components/schemas/DisbursementSnapshot'
    FirmUpdated:
      name: firm.updated
      summary: Sent when a Firm is updated, including every firm.status change.
      traits:
      - $ref: '#/components/messageTraits/ConfidoWebhook'
      payload:
        $ref: '#/components/schemas/EventEnvelope'
    StatementCreated:
      name: statement.created
      summary: Emitted when a monthly statement has been created for a Firm.
      traits:
      - $ref: '#/components/messageTraits/ConfidoWebhook'
      payload:
        $ref: '#/components/schemas/EventEnvelope'
    StatementUpdated:
      name: statement.updated
      summary: Emitted if a statement is updated. Documented as very unlikely — statements should be final
        at statement.created.
      traits:
      - $ref: '#/components/messageTraits/ConfidoWebhook'
      payload:
        $ref: '#/components/schemas/EventEnvelope'
    StoredPaymentMethodCreated:
      name: stored_payment_method.created
      traits:
      - $ref: '#/components/messageTraits/ConfidoWebhook'
      payload:
        $ref: '#/components/schemas/EventEnvelope'
    StoredPaymentMethodUpdated:
      name: stored_payment_method.updated
      traits:
      - $ref: '#/components/messageTraits/ConfidoWebhook'
      payload:
        $ref: '#/components/schemas/EventEnvelope'
    StoredPaymentMethodDeleted:
      name: stored_payment_method.deleted
      traits:
      - $ref: '#/components/messageTraits/ConfidoWebhook'
      payload:
        $ref: '#/components/schemas/EventEnvelope'
    StoredDisbursementMethodCreated:
      name: stored_disbursement_method.created
      traits:
      - $ref: '#/components/messageTraits/ConfidoWebhook'
      payload:
        $ref: '#/components/schemas/EventEnvelope'
    StoredDisbursementMethodUpdated:
      name: stored_disbursement_method.updated
      traits:
      - $ref: '#/components/messageTraits/ConfidoWebhook'
      payload:
        $ref: '#/components/schemas/EventEnvelope'
    StoredDisbursementMethodDeleted:
      name: stored_disbursement_method.deleted
      traits:
      - $ref: '#/components/messageTraits/ConfidoWebhook'
      payload:
        $ref: '#/components/schemas/EventEnvelope'