> ## Documentation Index > Fetch the complete documentation index at: https://docs.qonto.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a new webhook subscription > OAuth scopes: `webhook` + the scope(s) required for the webhook(s) you want to receive (cf. [Supported webhooks](/api-reference/business-api/webhooks/supported-webhooks)). > Example: if you want to receive a webhook every time a transaction is created or updated, you need the `organization.read` scope on top of the `webhook` scope. Subscribe to receive webhooks for specific event types. ## OpenAPI ````yaml post /v2/webhook_subscriptions openapi: 3.1.1 info: version: v2 title: Qonto servers: - url: https://thirdparty.qonto.com description: Production URL - url: https://thirdparty-sandbox.staging.qonto.co description: Sandbox URL security: - OAuth: - organization.read - membership.read - membership.write - attachment.write - internal_transfer.write - payment.write - supplier_invoice.write - supplier_invoice.read - client_invoices.read - client_invoice.write - client.read - client.write - product.read - product.write - request_review.write - request_review.read - team.read - team.write - request_transfers.write - insurance_contract.read - insurance_contract.write - card.read - card.write - bank_account.write - beneficiary.trust - webhook - payment_link.write - payment_link.read - sepa_direct_debit.read - sepa_direct_debit.write - terminal.read - terminal.write - SecretKey: [] paths: /v2/webhook_subscriptions: post: tags: - Webhooks summary: Create a new webhook subscription description: >- OAuth scopes: `webhook` + the scope(s) required for the webhook(s) you want to receive (cf. [Supported webhooks](/api-reference/business-api/webhooks/supported-webhooks)). > Example: if you want to receive a webhook every time a transaction is created or updated, you need the `organization.read` scope on top of the `webhook` scope. Subscribe to receive webhooks for specific event types. operationId: createWebhookSubscription requestBody: required: true content: application/json: schema: type: object required: - callback_url - types properties: callback_url: type: string format: uri pattern: ^https://.* maxLength: 512 description: The HTTPS URL where webhooks will be sent example: https://api.partner.com/webhooks/qonto types: $ref: '#/components/schemas/WebhookEventTypes' secret: type: string minLength: 32 maxLength: 128 description: >- Secret key for verifying webhook signatures. If not provided, one will be generated example: whsec_VuvcYxzMbryt1UBytq58jtGBxCgbQdzX/c0vj5ZLjUA= description: type: string description: Optional description for the webhook subscription example: Production webhook for transactions responses: '201': description: Webhook subscription created successfully content: application/json: schema: $ref: '#/components/schemas/WebhookSubscriptionDataWithSecret' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' security: - OAuth: - webhook components: schemas: WebhookEventTypes: type: array description: The types of events to subscribe to minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/WebhookEventType' example: - v1/transactions - v1/accounts - v1/organizations - v1/memberships - v1/consent-revocations - v1/cards - v1/payment-links - v1/payment-links-connections - v1/beneficiaries - v1/client-invoices - v1/terminal-payments WebhookSubscriptionDataWithSecret: allOf: - $ref: '#/components/schemas/WebhookSubscriptionData' - type: object properties: secret: type: string minLength: 32 maxLength: 128 description: Secret key for verifying webhook signatures. example: whsec_VuvcYxzMbryt1UBytq58jtGBxCgbQdzX/c0vj5ZLjUA= BadRequestError: type: object properties: code: type: string description: Error code. detail: type: string description: Human readable error that explains error `code`. source: type: object properties: pointer: type: string description: >- The property in the request body that caused the error (optional). parameter: type: string description: The query parameter that caused the error (optional). required: - code - detail x-examples: Authorization field missing: code: bad_request detail: Authorization field missing UnauthorizedError: type: object properties: code: type: string description: Error code. detail: type: string description: Human readable error that explains error `code`. required: - code - detail x-examples: Invalid credentials: code: unauthorized detail: Invalid credentials ForbiddenError: type: object properties: code: type: string description: Error code. detail: type: string description: Human readable error that explains error `code`. required: - code - detail x-examples: Insufficient permissions: code: forbidden detail: User does not have sufficient permissions for this action. WebhookEventType: type: string enum: - v1/transactions - v1/accounts - v1/organizations - v1/memberships - v1/consent-revocations - v1/cards - v1/payment-links - v1/payment-links-connections - v1/beneficiaries - v1/client-invoices - v1/terminal-payments example: v1/transactions WebhookSubscriptionData: type: object required: - id - organization_id - membership_id - callback_url - types - created_at - updated_at properties: id: type: string format: uuid description: Unique identifier for the webhook subscription example: 123e4567-e89b-12d3-a456-426614174000 organization_id: type: string format: uuid description: ID of the organization that owns this subscription example: 123e4567-e89b-12d3-a456-426614174000 membership_id: type: string format: uuid description: ID of the membership that owns this subscription example: 123e4567-e89b-12d3-a456-426614174000 callback_url: type: string format: uri pattern: ^https://.* maxLength: 512 description: The HTTPS URL where webhooks will be sent example: https://api.partner.com/webhooks/qonto types: $ref: '#/components/schemas/WebhookEventTypes' description: type: string maxLength: 256 description: Optional description for the webhook subscription example: Production webhook for transactions created_at: type: string format: date-time description: When the subscription was created example: '2025-01-24T10:55:00Z' updated_at: type: string format: date-time description: When the subscription was last updated example: '2025-01-24T10:55:00Z' securitySchemes: OAuth: type: oauth2 description: > Bearer authorization header: `Bearer `, where `` is the access token received from the authorization server at the end of the [OAuth 2.0 flow](/get-started/business-api/authentication/oauth/oauth-flow). flows: authorizationCode: refreshUrl: https://oauth.qonto.com/oauth2/token authorizationUrl: https://oauth.qonto.com/oauth2/auth scopes: attachment.read: Retrieve attachments attachment.write: Upload attachments and remove attachments from transactions bank_account.write: Create, update and close bank accounts beneficiary.trust: Trust SEPA beneficiaries card.read: Retrieve cards card.write: Create or update cards client.read: Retrieve clients client.write: Create clients client_invoice.write: Create client invoices client_invoices.read: Retrieve client invoices and credit notes einvoicing.read: Retrieve e-invoicing settings embed_auth_link.write: Create Embed auth links insurance_contract.read: Retrieve insurance contracts insurance_contract.write: Create and update insurance contracts internal_transfer.write: >- Create internal transfers (between 2 Qonto accounts of the same organization) international_transfer.write: Create international transfers membership.read: Retrieve the authentified membership membership.write: Invite team members offline_access: Retrieve a refresh token organization.read: >- Retrieve organization, bank accounts, transactions, transfers, beneficiaries, labels, memberships, requests & statements payment.write: Create external transfers and untrust beneficiaries payment_link.read: >- Retrieve payment links, their payments, and the available payment methods payment_link.write: >- Connect to the payment links provider, create and deactivate payment links product.read: Retrieve products product.write: Create products request_cards.write: Create card requests request_review.write: Approve or decline requests request_transfers.write: Create transfer requests sepa_direct_debit.read: View SEPA Direct Debit payments sepa_direct_debit.write: Manage SEPA Direct Debit payments supplier_invoice.read: Retrieve supplier invoices supplier_invoice.write: Create supplier invoices team.read: Retrieve teams team.write: Create teams terminal.read: View your payment terminals terminal.write: Configure your terminals and initiate payments webhook: >- Receive a notification each time a particular event occurs in Qonto tokenUrl: https://oauth.qonto.com/oauth2/token SecretKey: type: apiKey description: cf. [API key](/get-started/business-api/authentication/api-key) name: Authorization in: header ````