sxchnge/backend/contracts/sendico/models/callback/callback.yaml

components:
  schemas:
    CallbackBackoff:
      description: Backoff window used between callback retry attempts.
      type: object
      additionalProperties: false
      required:
        - minDelayMs
        - maxDelayMs
      properties:
        minDelayMs:
          description: Minimum delay in milliseconds before scheduling a retry attempt.
          type: integer
          minimum: 1
        maxDelayMs:
          description: Maximum delay in milliseconds before scheduling a retry attempt.
          type: integer
          minimum: 1

    CallbackRetryPolicy:
      description: Retry and delivery behavior for callback requests.
      type: object
      additionalProperties: false
      required:
        - backoff
        - signingMode
        - maxAttempts
        - requestTimeoutMs
      properties:
        backoff:
          description: Delay boundaries used to compute retry backoff between attempts.
          $ref: '#/components/schemas/CallbackBackoff'
        signingMode:
          description: Request-signing strategy applied when dispatching callback payloads. `jws_eddsa_ed25519` sends the raw JSON body unchanged and includes a detached compact JWS in `X-Callback-JWS`.
          type: string
          enum:
            - none
            - hmac_sha256
            - jws_eddsa_ed25519
        headers:
          description: Additional HTTP headers included with every callback request.
          type: object
          additionalProperties:
            type: string
        maxAttempts:
          description: Maximum number of delivery attempts before marking dispatch as failed.
          type: integer
          minimum: 1
        requestTimeoutMs:
          description: Per-request timeout in milliseconds for callback HTTP calls.
          type: integer
          minimum: 1

    CallbackSigningJWK:
      description: Ed25519 verification key published for callbacks that use detached JWS signing.
      type: object
      additionalProperties: false
      required:
        - kty
        - crv
        - alg
        - use
        - kid
        - x
      properties:
        kty:
          type: string
          enum: [OKP]
        crv:
          type: string
          enum: [Ed25519]
        alg:
          type: string
          enum: [EdDSA]
        use:
          type: string
          enum: [sig]
        kid:
          description: Opaque key identifier mirrored into the protected JWS header and `X-Callback-Key-Id`.
          type: string
        x:
          description: Base64url-encoded Ed25519 public key bytes used to verify the detached JWS signature.
          type: string

    CallbackSigningKey:
      description: Verification material exposed for callbacks that use `jws_eddsa_ed25519`. Receivers verify `X-Callback-JWS` against the raw request body with the matching `kid`. Retiring keys remain available for 24 hours after rotation so queued deliveries remain verifiable.
      type: object
      additionalProperties: false
      required:
        - status
        - jwk
      properties:
        status:
          description: Indicates whether the key is the current signing key or a still-valid retiring key from a recent rotation.
          type: string
          enum:
            - active
            - retiring
        expiresAt:
          description: Timestamp after which a retiring key is no longer returned in callback reads.
          type: string
          format: date-time
          nullable: true
        jwk:
          $ref: '#/components/schemas/CallbackSigningJWK'

    CallbackContent:
      description: Callback endpoint configuration and delivery parameters.
      allOf:
        - type: object
          additionalProperties: false
          required:
            - status
            - url
            - eventTypes
            - retryPolicy
          properties:
            status:
              description: Operational state controlling whether callback delivery is enabled.
              type: string
              enum:
                - active
                - disabled
            url:
              description: Absolute HTTPS endpoint URL that receives callback events.
              type: string
              format: uri
            eventTypes:
              description: Event type names that trigger callback delivery to this endpoint.
              type: array
              items:
                type: string
            retryPolicy:
              description: Retry and timeout parameters used when dispatching callback events.
              $ref: '#/components/schemas/CallbackRetryPolicy'


    Callback:
      description: Stored callback configuration bound to an organization permission scope.
      allOf:
        - $ref: ../permission_bound.yaml#/components/schemas/PermissionBound
        - $ref: ../common/describable.yaml#/components/schemas/Describable
        - $ref: '#/components/schemas/CallbackContent'
        - type: object
          additionalProperties: false
          properties:
            signingKeys:
              description: Read-only verification keys for callbacks that use detached JWS signing. The callback JSON body is not wrapped; receivers verify `X-Callback-JWS` against the raw body bytes and use the key matching the protected-header `kid`.
              type: array
              readOnly: true
              items:
                $ref: '#/components/schemas/CallbackSigningKey'