# Webhooks for Partners Source: https://docs.gocardless.com/docs/partner-integrations/webhooks-for-partners # Webhooks for partners A webhook is a real-time request that GoCardless sends to your server to alert you of an event. Adding support for webhooks allows you to receive real-time notifications from GoCardless when events happen in your account, so you can take automated actions. **This is the suggested monitoring approach.** A webhook can contain multiple events, and each has: - a **resource_type**, telling us what kind of resource the event is for, for example, "payments" or "mandates" - an **action**, telling us what happened to the resource, for example, the "failed" action for a payment - **details**, specifying why the event happened ```json , "metadata": , "links": } } ``` > **Info: Stay up to date with webhooks** > Read more about how to create a secure webhook handler in the [staying up-to-date with > webhooks](/docs/getting-started/stay-up-to-date-with-webhooks) section. ## Key Webhook Events ### Billing Request Webhooks | **Event** | **Description** | **Suggested Handling** | | --------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | `flow_visited` | The billing request flow has been visited | Use to detect payer inactivity and expire the billing request if needed | | `flow_exited` | The payer exited the flow without completing it | Consider triggering a push notification for mobile experiences | | `bank_authorisation_denied` | A bank authorisation was denied by the payer | Display the denial reason from `details.description` | | `bank_authorisation_failed` | A bank authorisation failed due to a bank account mismatch | Display the failure reason from `details.description` | | `fulfilled` | The billing request was fulfilled and the mandate and/or payment have been created | Save the mandate and/or payment ID to your database | ![billing-request-state-diagram](/images/docs/partner-integrations/webhooks-for-partners/billing-request-state-diagram.png) See the full list of [billing request webhooks](/docs/api-reference/events/billing-requests) in the API reference. ### Mandate Webhooks | **Event** | **Description** | **Suggested Handling** | | ------------------------ | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | | `created` | The mandate has been created | Save the mandate ID to your database | | `submitted` | The mandate has been submitted to the banks | Update the mandate status in your billing system | | `active` | The mandate has been successfully set up by the customer's bank | Update the mandate status in your billing system | | `failed` | The mandate could not be set up — the bank account does not accept Direct Debit or is closed | Update status; allow the customer to use another payment method or re-attempt with a new account | | `cancelled` | The mandate was cancelled by the customer, via the API, or automatically when their account was closed | Update status; request a new payment method and cancel any associated subscriptions | | `expired` | No collections were made within the dormancy period and the mandate has expired | Update status; use the [reinstate endpoint](/docs/api-reference/responses-and-errors#invalid-state) or create a new mandate | | `resubmission_requested` | A reinstate request was made via the mandate reinstate endpoint | Update the mandate status in your billing system | | `reinstated` | The mandate has become active again after being cancelled or expired | Update the mandate status in your billing system | | `replaced` | The mandate was cancelled and replaced by a new one. The event includes `links.new_mandate` | Update the stored mandate ID to the value in `links.new_mandate` | | `blocked` | The mandate matched fraud information or a block list and cannot be unblocked | Update status; cancel any subscriptions against this mandate | ![mandate-state-diagram](/images/docs/partner-integrations/webhooks-for-partners/mandate-state-diagram.png) See the full list of [mandate webhooks](/docs/api-reference/events/mandates) in the API reference. ### Payment Webhooks | **Event** | **Description** | **Suggested Handling** | | ------------------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | | `created` | The payment has been created | Save the payment ID to your database | | `submitted` | The payment has been submitted to the banks | Update the payment status in your billing system | | `confirmed` | The payment has been collected and is held by GoCardless before payout | Update the payment and invoice status | | `paid_out` | The payment has been sent to the creditor's bank account | Update the payment and invoice status | | `failed` | The payment could not be collected. If `will_attempt_retry` is true, Success+ will retry automatically | Update the payment and invoice status | | `cancelled` | The payment was cancelled | Update the payment and invoice status | | `resubmission_requested` | Success+ has scheduled an automatic retry (see `failed`) | Update the payment and invoice status | | `charged_back` | The customer reclaimed the payment via the Direct Debit Guarantee | Update the payment and invoice status | | `chargeback_cancelled` | The customer's bank cancelled the chargeback request | Update the payment and invoice status | ![payment-state-diagram](/images/docs/partner-integrations/webhooks-for-partners/payment-state-diagram.png) See the full list of [payment webhooks](/docs/api-reference/events/payments) in the API reference. ### Refund Webhooks | **Event** | **Description** | **Suggested Handling** | | --------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | `created` | A refund has been created (`details.cause`: `payment_refunded`, `details.origin`: `api`) | Update the refund status and expose it to your merchants | | `failed` | The refund did not reach the customer; funds are returned to you (`details.cause`: `refund_failed`) | Update the refund status and expose it to your merchants | | `paid` | The refund has been paid to the customer (`details.cause`: `refund_paid`) | Update the refund status and expose it to your merchants | See the full list of [refund webhooks](/docs/api-reference/events/refunds) in the API reference. ## What's Next? #### [Stay up to date with webhooks](/docs/getting-started/stay-up-to-date-with-webhooks) Learn how to create a secure webhook endpoint and verify webhook signatures. #### [Go-live checklist](/docs/partner-integrations/go-live-checklist) Complete the self-assessment review and submit your integration for approval.