{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/pluggy/json-schema/pluggy-webhook-schema.json",
  "title": "Webhook",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/pluggy-webhook-api-openapi.yml#/components/schemas/Webhook",
  "properties": {
    "id": {
      "type": "string",
      "description": "UUID identifier for the entity"
    },
    "url": {
      "type": "string",
      "description": "Url to be notified of item changes"
    },
    "event": {
      "$ref": "#/$defs/WebhookEventType"
    },
    "disabledAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Date when the webhook was disabled"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Date when it was created"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Date of the last update"
    },
    "headers": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Custom headers sent with each webhook delivery. Always present; an empty object when none are configured"
    }
  },
  "type": "object",
  "required": [
    "id",
    "url",
    "event",
    "headers"
  ],
  "$defs": {
    "WebhookEventType": {
      "type": "string",
      "enum": [
        "all",
        "item/created",
        "item/updated",
        "item/error",
        "item/deleted",
        "item/waiting_user_input",
        "item/waiting_user_action",
        "item/login_succeeded",
        "connector/status_updated",
        "transactions/created",
        "transactions/updated",
        "transactions/deleted",
        "payment_intent/created",
        "payment_intent/completed",
        "payment_intent/waiting_payer_authorization",
        "payment_intent/error",
        "payment_request/updated",
        "scheduled_payment/created",
        "scheduled_payment/completed",
        "scheduled_payment/error",
        "scheduled_payment/canceled",
        "scheduled_payment/all_completed",
        "scheduled_payment/all_created",
        "boleto/updated",
        "automatic_pix_payment/created",
        "automatic_pix_payment/completed",
        "automatic_pix_payment/error",
        "automatic_pix_payment/canceled",
        "smart_transfer_preauthorization/completed",
        "smart_transfer_preauthorization/error",
        "smart_transfer_payment/completed",
        "smart_transfer_payment/error"
      ],
      "description": "Event the webhook subscribes to. Use `all` to receive every event for the client. Events are grouped by topic:\n\n**item/** – Lifecycle of an item (a connection to a financial institution).\n- `item/created`: a new item was created.\n- `item/updated`: the item finished an execution with new data.\n- `item/error`: the execution finished with an error (see the payload's `error` field).\n- `item/deleted`: the item was deleted.\n- `item/waiting_user_input`: the item needs additional credentials/MFA from the end user.\n- `item/waiting_user_action`: the item needs the end user to perform an action on the institution side.\n- `item/login_succeeded`: the credentials were accepted by the institution (data may still be syncing).\n\n**connector/** – Connector-level events.\n- `connector/status_updated`: a connector's health status changed (ONLINE/OFFLINE/UNSTABLE).\n\n**transactions/** – Account transaction lifecycle.\n- `transactions/created` / `transactions/updated` / `transactions/deleted`: a transaction was inserted, modified or removed during an item execution.\n\n**payment_intent/** – Payment Initiation flow (single PIX).\n- `payment_intent/created`: a payment intent was created.\n- `payment_intent/completed`: the payment was confirmed by the institution.\n- `payment_intent/waiting_payer_authorization`: the payer still needs to authorize the payment.\n- `payment_intent/error`: the payment was rejected or failed.\n\n**payment_request/** – Aggregate payment request state.\n- `payment_request/updated`: the overall status of a payment request changed.\n\n**scheduled_payment/** – Scheduled (recurring or future) payments.\n- `scheduled_payment/created` / `completed` / `error` / `canceled`: lifecycle of a single scheduled payment.\n- `scheduled_payment/all_created` / `scheduled_payment/all_completed`: emitted once when every scheduled payment in a series reaches the same terminal state.\n\n**boleto/** – Boleto status updates.\n- `boleto/updated`: the boleto data was updated (e.g. paid, expired, amount changed).\n\n**automatic_pix_payment/** – Recurring PIX (PIX Automático) individual payments.\n- `automatic_pix_payment/created`: a new recurring payment was scheduled.\n- `automatic_pix_payment/completed`: the recurring payment was confirmed.\n- `automatic_pix_payment/error`: the recurring payment failed.\n- `automatic_pix_payment/canceled`: the recurring payment was canceled (by user, expiration or revoked consent).\n\n**smart_transfer_preauthorization/** – Smart Transfer pre-authorization (consent setup).\n- `smart_transfer_preauthorization/completed`: the pre-authorization was accepted.\n- `smart_transfer_preauthorization/error`: the pre-authorization failed.\n\n**smart_transfer_payment/** – Smart Transfer individual payments executed under an active pre-authorization.\n- `smart_transfer_payment/completed`: the transfer was successful.\n- `smart_transfer_payment/error`: the transfer failed."
    }
  }
}