{
  "asyncapi": "3.0.0",
  "id": "urn:com:ai2fin:webhooks",
  "info": {
    "title": "2Fin Webhooks",
    "version": "1.0.0",
    "description": "The events 2Fin sends to your webhook subscriptions: transaction.categorized, expense.created, receipt.processed and the ping test. Each delivery is an HTTPS POST signed with your subscription secret in the X-AI2Fin-Signature header. Requires the Auto+ plan. Derived from the webhooks object in https://docs.ai2fin.com/api-reference/openapi.json; the guide is https://docs.ai2fin.com/api-reference/webhooks.",
    "contact": {
      "name": "AI2Fin Support",
      "url": "https://ai2fin.com/contact",
      "email": "support@ai2fin.com"
    },
    "termsOfService": "https://ai2fin.com/terms",
    "externalDocs": {
      "description": "Webhooks guide",
      "url": "https://docs.ai2fin.com/api-reference/webhooks"
    },
    "tags": [
      {
        "name": "Webhooks"
      }
    ]
  },
  "defaultContentType": "application/json",
  "servers": {
    "subscriber": {
      "host": "your-endpoint.example",
      "protocol": "https",
      "title": "Your webhook endpoint",
      "description": "The HTTPS URL you register with POST /api/automations/webhooks. 2Fin connects to it; it is not a 2Fin host.",
      "security": [
        {
          "$ref": "#/components/securitySchemes/webhookSignature"
        }
      ],
      "bindings": {
        "http": {
          "bindingVersion": "0.3.0"
        }
      }
    }
  },
  "channels": {
    "transaction_categorized": {
      "address": null,
      "title": "transaction.categorized",
      "description": "Delivered to the HTTPS URL of each active webhook subscription for `transaction.categorized`.",
      "messages": {
        "transaction_categorized": {
          "$ref": "#/components/messages/transaction_categorized"
        }
      }
    },
    "expense_created": {
      "address": null,
      "title": "expense.created",
      "description": "Delivered to the HTTPS URL of each active webhook subscription for `expense.created`.",
      "messages": {
        "expense_created": {
          "$ref": "#/components/messages/expense_created"
        }
      }
    },
    "receipt_processed": {
      "address": null,
      "title": "receipt.processed",
      "description": "Delivered to the HTTPS URL of each active webhook subscription for `receipt.processed`.",
      "messages": {
        "receipt_processed": {
          "$ref": "#/components/messages/receipt_processed"
        }
      }
    },
    "ping": {
      "address": null,
      "title": "ping",
      "description": "Delivered to the HTTPS URL of each active webhook subscription for `ping`.",
      "messages": {
        "ping": {
          "$ref": "#/components/messages/ping"
        }
      }
    }
  },
  "operations": {
    "receive_transaction_categorized": {
      "action": "receive",
      "title": "A transaction reached its categorized state",
      "description": "Fired when the processing pipeline finishes categorizing transactions (by your rules, patterns, receipts or the AI). `source` says where the row came from; bank-feed rows are included and labelled `bank_feed`. Sent as an HTTPS POST (Content-Type application/json, User-Agent AI2Fin-Webhooks/1.0) to each active subscription for the event, signed with its secret. Requires the Auto+ plan.",
      "channel": {
        "$ref": "#/channels/transaction_categorized"
      },
      "messages": [
        {
          "$ref": "#/channels/transaction_categorized/messages/transaction_categorized"
        }
      ],
      "security": [
        {
          "$ref": "#/components/securitySchemes/webhookSignature"
        }
      ],
      "bindings": {
        "http": {
          "method": "POST",
          "bindingVersion": "0.3.0"
        }
      }
    },
    "receive_expense_created": {
      "action": "receive",
      "title": "An expense was created",
      "description": "Fired when you create an expense in the app (POST /api/expenses) or through the Integration API (POST /api/integrations/v1/expenses). Sent as an HTTPS POST (Content-Type application/json, User-Agent AI2Fin-Webhooks/1.0) to each active subscription for the event, signed with its secret. Requires the Auto+ plan.",
      "channel": {
        "$ref": "#/channels/expense_created"
      },
      "messages": [
        {
          "$ref": "#/channels/expense_created/messages/expense_created"
        }
      ],
      "security": [
        {
          "$ref": "#/components/securitySchemes/webhookSignature"
        }
      ],
      "bindings": {
        "http": {
          "method": "POST",
          "bindingVersion": "0.3.0"
        }
      }
    },
    "receive_receipt_processed": {
      "action": "receive",
      "title": "A receipt was committed",
      "description": "Fired when a receipt is committed (POST /api/receipts/commit). Sent as an HTTPS POST (Content-Type application/json, User-Agent AI2Fin-Webhooks/1.0) to each active subscription for the event, signed with its secret. Requires the Auto+ plan.",
      "channel": {
        "$ref": "#/channels/receipt_processed"
      },
      "messages": [
        {
          "$ref": "#/channels/receipt_processed/messages/receipt_processed"
        }
      ],
      "security": [
        {
          "$ref": "#/components/securitySchemes/webhookSignature"
        }
      ],
      "bindings": {
        "http": {
          "method": "POST",
          "bindingVersion": "0.3.0"
        }
      }
    },
    "receive_ping": {
      "action": "receive",
      "title": "Test delivery",
      "description": "Sent only when you ask for a test (POST /api/automations/webhooks/{id}/test). Has no `apiVersion`. Sent as an HTTPS POST (Content-Type application/json, User-Agent AI2Fin-Webhooks/1.0) to each active subscription for the event, signed with its secret. Requires the Auto+ plan.",
      "channel": {
        "$ref": "#/channels/ping"
      },
      "messages": [
        {
          "$ref": "#/channels/ping/messages/ping"
        }
      ],
      "security": [
        {
          "$ref": "#/components/securitySchemes/webhookSignature"
        }
      ],
      "bindings": {
        "http": {
          "method": "POST",
          "bindingVersion": "0.3.0"
        }
      }
    }
  },
  "components": {
    "messages": {
      "transaction_categorized": {
        "name": "transaction.categorized",
        "title": "A transaction reached its categorized state",
        "summary": "A transaction reached its categorized state",
        "description": "Fired when the processing pipeline finishes categorizing transactions (by your rules, patterns, receipts or the AI). `source` says where the row came from; bank-feed rows are included and labelled `bank_feed`. Sent as an HTTPS POST (Content-Type application/json, User-Agent AI2Fin-Webhooks/1.0) to each active subscription for the event, signed with its secret. Requires the Auto+ plan.",
        "contentType": "application/json",
        "headers": {
          "type": "object",
          "required": [
            "X-AI2Fin-Signature",
            "X-AI2Fin-Event",
            "X-AI2Fin-Delivery"
          ],
          "properties": {
            "X-AI2Fin-Signature": {
              "type": "string",
              "description": "`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with your signing secret>`. During the 24 hours after a secret rotation a second `v1=` (previous secret) is appended. Reject timestamps more than 5 minutes off."
            },
            "X-AI2Fin-Event": {
              "type": "string"
            },
            "X-AI2Fin-Delivery": {
              "type": "string",
              "description": "The delivery id. Automatic retries of a delivery keep the same id, so use it to de-duplicate; a manual redelivery gets a new id."
            }
          }
        },
        "payload": {
          "$ref": "#/components/schemas/WebhookTransactionCategorized"
        },
        "examples": [
          {
            "name": "transaction.categorized",
            "payload": {
              "event": "transaction.categorized",
              "apiVersion": "2026-07-01",
              "createdAt": "2026-11-12T03:14:07.000Z",
              "data": {
                "id": "cmh1x2y3z0001ab12cd34ef56",
                "amount": -42.5,
                "date": "2026-11-10T00:00:00.000Z",
                "merchant": "Officeworks",
                "category": "Office Supplies",
                "source": "csv_import"
              }
            }
          }
        ],
        "bindings": {
          "http": {
            "bindingVersion": "0.3.0"
          }
        }
      },
      "expense_created": {
        "name": "expense.created",
        "title": "An expense was created",
        "summary": "An expense was created",
        "description": "Fired when you create an expense in the app (POST /api/expenses) or through the Integration API (POST /api/integrations/v1/expenses). Sent as an HTTPS POST (Content-Type application/json, User-Agent AI2Fin-Webhooks/1.0) to each active subscription for the event, signed with its secret. Requires the Auto+ plan.",
        "contentType": "application/json",
        "headers": {
          "type": "object",
          "required": [
            "X-AI2Fin-Signature",
            "X-AI2Fin-Event",
            "X-AI2Fin-Delivery"
          ],
          "properties": {
            "X-AI2Fin-Signature": {
              "type": "string",
              "description": "`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with your signing secret>`. During the 24 hours after a secret rotation a second `v1=` (previous secret) is appended. Reject timestamps more than 5 minutes off."
            },
            "X-AI2Fin-Event": {
              "type": "string"
            },
            "X-AI2Fin-Delivery": {
              "type": "string",
              "description": "The delivery id. Automatic retries of a delivery keep the same id, so use it to de-duplicate; a manual redelivery gets a new id."
            }
          }
        },
        "payload": {
          "$ref": "#/components/schemas/WebhookExpenseCreated"
        },
        "examples": [
          {
            "name": "expense.created",
            "payload": {
              "event": "expense.created",
              "apiVersion": "2026-07-01",
              "createdAt": "2026-11-12T03:15:00.000Z",
              "data": {
                "id": "cmh1x3a4b0002ab12cd34ef56",
                "amount": 89,
                "date": "2026-11-11T00:00:00.000Z",
                "merchant": "Telstra",
                "category": null,
                "source": "manual"
              }
            }
          }
        ],
        "bindings": {
          "http": {
            "bindingVersion": "0.3.0"
          }
        }
      },
      "receipt_processed": {
        "name": "receipt.processed",
        "title": "A receipt was committed",
        "summary": "A receipt was committed",
        "description": "Fired when a receipt is committed (POST /api/receipts/commit). Sent as an HTTPS POST (Content-Type application/json, User-Agent AI2Fin-Webhooks/1.0) to each active subscription for the event, signed with its secret. Requires the Auto+ plan.",
        "contentType": "application/json",
        "headers": {
          "type": "object",
          "required": [
            "X-AI2Fin-Signature",
            "X-AI2Fin-Event",
            "X-AI2Fin-Delivery"
          ],
          "properties": {
            "X-AI2Fin-Signature": {
              "type": "string",
              "description": "`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with your signing secret>`. During the 24 hours after a secret rotation a second `v1=` (previous secret) is appended. Reject timestamps more than 5 minutes off."
            },
            "X-AI2Fin-Event": {
              "type": "string"
            },
            "X-AI2Fin-Delivery": {
              "type": "string",
              "description": "The delivery id. Automatic retries of a delivery keep the same id, so use it to de-duplicate; a manual redelivery gets a new id."
            }
          }
        },
        "payload": {
          "$ref": "#/components/schemas/WebhookReceiptProcessed"
        },
        "examples": [
          {
            "name": "receipt.processed",
            "payload": {
              "event": "receipt.processed",
              "apiVersion": "2026-07-01",
              "createdAt": "2026-11-12T03:16:30.000Z",
              "data": {
                "id": "cmh1x4c5d0003ab12cd34ef56",
                "amount": 23.9,
                "date": "2026-11-09",
                "merchant": "Bunnings",
                "category": null,
                "source": "receipt"
              }
            }
          }
        ],
        "bindings": {
          "http": {
            "bindingVersion": "0.3.0"
          }
        }
      },
      "ping": {
        "name": "ping",
        "title": "Test delivery",
        "summary": "Test delivery",
        "description": "Sent only when you ask for a test (POST /api/automations/webhooks/{id}/test). Has no `apiVersion`. Sent as an HTTPS POST (Content-Type application/json, User-Agent AI2Fin-Webhooks/1.0) to each active subscription for the event, signed with its secret. Requires the Auto+ plan.",
        "contentType": "application/json",
        "headers": {
          "type": "object",
          "required": [
            "X-AI2Fin-Signature",
            "X-AI2Fin-Event",
            "X-AI2Fin-Delivery"
          ],
          "properties": {
            "X-AI2Fin-Signature": {
              "type": "string",
              "description": "`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with your signing secret>`. During the 24 hours after a secret rotation a second `v1=` (previous secret) is appended. Reject timestamps more than 5 minutes off."
            },
            "X-AI2Fin-Event": {
              "type": "string"
            },
            "X-AI2Fin-Delivery": {
              "type": "string",
              "description": "The delivery id. Automatic retries of a delivery keep the same id, so use it to de-duplicate; a manual redelivery gets a new id."
            }
          }
        },
        "payload": {
          "$ref": "#/components/schemas/WebhookPing"
        },
        "examples": [
          {
            "name": "ping",
            "payload": {
              "event": "ping",
              "createdAt": "2026-11-12T03:17:00.000Z",
              "data": {
                "message": "AI2Fin webhook test delivery"
              }
            }
          }
        ],
        "bindings": {
          "http": {
            "bindingVersion": "0.3.0"
          }
        }
      }
    },
    "schemas": {
      "WebhookTransactionCategorized": {
        "type": "object",
        "required": [
          "event",
          "apiVersion",
          "createdAt",
          "data"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "transaction.categorized"
          },
          "apiVersion": {
            "type": "string",
            "const": "2026-07-01"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object",
            "required": [
              "id",
              "amount",
              "date",
              "source"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "amount": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "date": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ISO 8601 date or date-time."
              },
              "merchant": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "category": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Present only when the subscription opted into `description`."
              },
              "source": {
                "type": "string",
                "enum": [
                  "bank_feed",
                  "csv_import",
                  "api",
                  "manual"
                ]
              }
            }
          }
        },
        "example": {
          "event": "transaction.categorized",
          "apiVersion": "2026-07-01",
          "createdAt": "2026-11-12T03:14:07.000Z",
          "data": {
            "id": "cmh1x2y3z0001ab12cd34ef56",
            "amount": -42.5,
            "date": "2026-11-10T00:00:00.000Z",
            "merchant": "Officeworks",
            "category": "Office Supplies",
            "source": "csv_import"
          }
        }
      },
      "WebhookExpenseCreated": {
        "type": "object",
        "required": [
          "event",
          "apiVersion",
          "createdAt",
          "data"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "expense.created"
          },
          "apiVersion": {
            "type": "string",
            "const": "2026-07-01"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object",
            "required": [
              "id",
              "amount",
              "date",
              "source"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "amount": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "date": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ISO 8601 date or date-time."
              },
              "merchant": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "category": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Present only when the subscription opted into `description`."
              },
              "source": {
                "type": "string",
                "const": "manual"
              }
            }
          }
        },
        "example": {
          "event": "expense.created",
          "apiVersion": "2026-07-01",
          "createdAt": "2026-11-12T03:15:00.000Z",
          "data": {
            "id": "cmh1x3a4b0002ab12cd34ef56",
            "amount": 89,
            "date": "2026-11-11T00:00:00.000Z",
            "merchant": "Telstra",
            "category": null,
            "source": "manual"
          }
        }
      },
      "WebhookReceiptProcessed": {
        "type": "object",
        "required": [
          "event",
          "apiVersion",
          "createdAt",
          "data"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "receipt.processed"
          },
          "apiVersion": {
            "type": "string",
            "const": "2026-07-01"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object",
            "required": [
              "id",
              "amount",
              "date",
              "source"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "amount": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "date": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ISO 8601 date or date-time."
              },
              "merchant": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "category": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "source": {
                "type": "string",
                "const": "receipt"
              }
            }
          }
        },
        "example": {
          "event": "receipt.processed",
          "apiVersion": "2026-07-01",
          "createdAt": "2026-11-12T03:16:30.000Z",
          "data": {
            "id": "cmh1x4c5d0003ab12cd34ef56",
            "amount": 23.9,
            "date": "2026-11-09",
            "merchant": "Bunnings",
            "category": null,
            "source": "receipt"
          }
        }
      },
      "WebhookPing": {
        "type": "object",
        "required": [
          "event",
          "createdAt",
          "data"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "ping"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              }
            }
          }
        },
        "example": {
          "event": "ping",
          "createdAt": "2026-11-12T03:17:00.000Z",
          "data": {
            "message": "AI2Fin webhook test delivery"
          }
        }
      }
    },
    "securitySchemes": {
      "webhookSignature": {
        "type": "httpApiKey",
        "name": "X-AI2Fin-Signature",
        "in": "header",
        "description": "`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" keyed with the subscription secret>`. Verify against the raw body before parsing and reject timestamps more than five minutes off."
      }
    }
  }
}
