> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GoCardless Webhook Setup Guide

> Configure GoCardless to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](/connectors/gocardless#getting-started) on the GoCardless connector page.

<section data-guide-section data-guide-scopes="">
  <h2>Retrieve the StackOne Native Webhook URL</h2>

  <p>The <strong>Native Webhook URL</strong> is generated once a GoCardless account has been linked in StackOne. Each linked account has its own URL.</p>

  <ul>
    <li>Open the linked account in StackOne.</li>
    <li>Copy the value from <strong>Native Webhook URL</strong>.</li>
  </ul>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Create a GoCardless webhook endpoint</h2>

  <p>Register the Native Webhook URL as a webhook endpoint in the GoCardless dashboard so GoCardless posts events to StackOne.</p>

  <Steps>
    <Step title="Open API settings">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Sign in to your <a href="https://manage.gocardless.com/sign-in" target="_blank" rel="noopener noreferrer">GoCardless dashboard</a> (or the <a href="https://manage-sandbox.gocardless.com/sign-in" target="_blank" rel="noopener noreferrer">GoCardless sandbox dashboard</a> for a sandbox account).</p>

        <ul>
          <li>In the left sidebar, click <strong>Developers</strong>, then select <strong>API settings</strong>.</li>
        </ul>

        <img src="https://mintcdn.com/stackone-60/NhoVxUwgPwyWbu51/connectors/gocardless/images/events-api-settings-menu.png?fit=max&auto=format&n=NhoVxUwgPwyWbu51&q=85&s=54f6d11d90ffae9422c22fcce21df227" alt="The expanded Developers menu in the GoCardless sidebar with API settings highlighted" width="1280" height="800" data-path="connectors/gocardless/images/events-api-settings-menu.png" />
      </div>
    </Step>

    <Step title="Open the webhook endpoint form">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>On the <strong>API Settings</strong> page, click <strong>Create</strong> in the top right corner, then select <strong>Webhook endpoint</strong>.</p>

        <ul>
          <li>The <strong>Webhook endpoints</strong> section on the same page lists any endpoints you have already created.</li>
        </ul>

        <img src="https://mintcdn.com/stackone-60/NhoVxUwgPwyWbu51/connectors/gocardless/images/events-create-webhook-endpoint-menu.png?fit=max&auto=format&n=NhoVxUwgPwyWbu51&q=85&s=f43b5a0594fdd049311e67762ba38143" alt="The Create dropdown on the API Settings page with the Webhook endpoint option highlighted" width="1280" height="800" data-path="connectors/gocardless/images/events-create-webhook-endpoint-menu.png" />
      </div>
    </Step>

    <Step title="Fill in the webhook endpoint details">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>In the <strong>Create webhook endpoint</strong> dialog, complete the form:</p>

        <ul>
          <li><strong>Name</strong> — enter a name for the endpoint (for example, `StackOne Integration`).</li>
          <li><strong>URL</strong> — paste the Native Webhook URL you copied from StackOne.</li>
          <li>Leave <strong>Generate a secret for me</strong> selected. StackOne does not need the secret.</li>
          <li><strong>Webhook client certificate</strong> is optional and can be left unchecked.</li>
        </ul>

        <img src="https://mintcdn.com/stackone-60/NhoVxUwgPwyWbu51/connectors/gocardless/images/events-create-webhook-endpoint-form.png?fit=max&auto=format&n=NhoVxUwgPwyWbu51&q=85&s=b03ed0b9525738db598d4c3a52846eaa" alt="The Create webhook endpoint dialog with the Name, URL, and Generate a secret for me options highlighted" width="1280" height="800" data-path="connectors/gocardless/images/events-create-webhook-endpoint-form.png" />
      </div>
    </Step>

    <Step title="Create the endpoint">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Click <strong>Create</strong> to save the webhook endpoint.</p>

        <img src="https://mintcdn.com/stackone-60/NhoVxUwgPwyWbu51/connectors/gocardless/images/events-create-webhook-endpoint-submit.png?fit=max&auto=format&n=NhoVxUwgPwyWbu51&q=85&s=cea165a7ab0051945dbf0f9840cdedb1" alt="The completed Create webhook endpoint dialog with the Create button highlighted" width="1280" height="800" data-path="connectors/gocardless/images/events-create-webhook-endpoint-submit.png" />
      </div>
    </Step>

    <Step title="Save the webhook secret">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>GoCardless shows <strong>Your webhook secret</strong> with the message <strong>Make sure to copy your webhook secret now. You won't be able to see it again.</strong></p>

        <ul>
          <li>Click <strong>Copy</strong> if you want to keep the secret for your own records, then click <strong>Done</strong>.</li>
          <li>The secret is only displayed once and cannot be retrieved later. You can generate a new one with <strong>Change secret</strong> on the endpoint's page.</li>
        </ul>

        <img src="https://mintcdn.com/stackone-60/NhoVxUwgPwyWbu51/connectors/gocardless/images/events-webhook-secret.png?fit=max&auto=format&n=NhoVxUwgPwyWbu51&q=85&s=02ac75aeb68f35e4904cb639d3801421" alt="The Your webhook secret dialog with the secret value hidden and the Copy and Done buttons highlighted" width="1280" height="800" data-path="connectors/gocardless/images/events-webhook-secret.png" />
      </div>
    </Step>

    <Step title="Confirm the endpoint is enabled">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>The new endpoint appears on the <strong>Webhook endpoints</strong> page with the status <strong>Enabled</strong>. GoCardless starts sending events to StackOne straight away.</p>

        <ul>
          <li>To stop deliveries later, open the endpoint and click <strong>Disable</strong>.</li>
        </ul>

        <img src="https://mintcdn.com/stackone-60/NhoVxUwgPwyWbu51/connectors/gocardless/images/events-webhook-endpoint-enabled.png?fit=max&auto=format&n=NhoVxUwgPwyWbu51&q=85&s=049e4159a2dec0f556f9aa389b11692a" alt="The Webhook endpoints list showing the StackOne Integration endpoint with the Enabled status" width="1280" height="800" data-path="connectors/gocardless/images/events-webhook-endpoint-enabled.png" />
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available webhook events</h2>

  <p>The following GoCardless events can be enabled in StackOne. GoCardless sends every event on the account to the endpoint; StackOne delivers only the events listed here and enabled for this connector, and acknowledges all others without forwarding them.</p>

  <Steps>
    <Step title="Payment events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for one-off and recurring Direct Debit payments.</p>

        <ul>
          <li><strong>Payment Created</strong> (`payments.created`) — The payment has been created</li>
          <li><strong>Payment Submitted</strong> (`payments.submitted`) — The payment has been submitted to the banks</li>
          <li><strong>Payment Confirmed</strong> (`payments.confirmed`) — The payment has been collected from the customer's bank account, and is now being held by GoCardless</li>
          <li><strong>Payment Paid Out</strong> (`payments.paid_out`) — The payment has left GoCardless and has been sent to the creditor's bank account</li>
          <li><strong>Payment Failed</strong> (`payments.failed`) — The payment could not be collected, usually because the customer did not have sufficient funds available</li>
          <li><strong>Payment Cancelled</strong> (`payments.cancelled`) — The payment was cancelled</li>
          <li><strong>Payment Resubmission Requested</strong> (`payments.resubmission_requested`) — A request to resubmit the payment was made by the payment retry endpoint</li>
          <li><strong>Payment Charged Back</strong> (`payments.charged_back`) — The customer asked their bank to refund the payment under the Direct Debit Guarantee, and it has been returned to the customer</li>
          <li><strong>Payment Chargeback Cancelled</strong> (`payments.chargeback_cancelled`) — The customer's bank has cancelled the chargeback request</li>
        </ul>
      </div>
    </Step>

    <Step title="Refund events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for refunds issued against payments.</p>

        <ul>
          <li><strong>Refund Failed</strong> (`refunds.failed`) — The refund did not reach your customer, the funds will be returned to you</li>
          <li><strong>Refund Paid</strong> (`refunds.paid`) — The refund has been paid to your customer</li>
        </ul>
      </div>
    </Step>

    <Step title="Payout events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for payouts sent to your bank account.</p>

        <ul>
          <li><strong>Payout Paid</strong> (`payouts.paid`) — GoCardless has transferred the payout to the creditor's bank account</li>
        </ul>
      </div>
    </Step>

    <Step title="Mandate events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for Direct Debit mandates.</p>

        <ul>
          <li><strong>Mandate Created</strong> (`mandates.created`) — The mandate has been created</li>
          <li><strong>Mandate Submitted</strong> (`mandates.submitted`) — The mandate has been submitted to the banks, and should become active in a few days, unless the bank declines the request</li>
          <li><strong>Mandate Active</strong> (`mandates.active`) — The mandate has been successfully set up by the customer's bank</li>
          <li><strong>Mandate Failed</strong> (`mandates.failed`) — The mandate could not be set up, generally because the specified bank account does not accept Direct Debit payments or is closed</li>
          <li><strong>Mandate Cancelled</strong> (`mandates.cancelled`) — The mandate has been cancelled, either by the customer through their bank or this API, or automatically when their bank account is closed</li>
          <li><strong>Mandate Expired</strong> (`mandates.expired`) — No collection attempts were made against the mandate within the dormancy period of your service user number</li>
          <li><strong>Mandate Reinstated</strong> (`mandates.reinstated`) — The mandate has become active again, after it was cancelled or expired</li>
          <li><strong>Mandate Replaced</strong> (`mandates.replaced`) — The mandate has been cancelled and replaced by a new mandate (for example, because the creditor has moved to a new Service User Number)</li>
        </ul>
      </div>
    </Step>

    <Step title="Billing request events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for the outcome of billing requests.</p>

        <ul>
          <li><strong>Billing Request Fulfilled</strong> (`billing_requests.fulfilled`) — This billing request has been fulfilled, and the resources have been created</li>
          <li><strong>Billing Request Cancelled</strong> (`billing_requests.cancelled`) — This billing request has been cancelled, none of the resources have been created</li>
          <li><strong>Billing Request Failed</strong> (`billing_requests.failed`) — This billing request has failed</li>
        </ul>
      </div>
    </Step>

    <Step title="Subscription events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for recurring subscriptions.</p>

        <ul>
          <li><strong>Subscription Created</strong> (`subscriptions.created`) — The subscription has been created</li>
          <li><strong>Subscription Amended</strong> (`subscriptions.amended`) — The subscription amount has been changed</li>
          <li><strong>Subscription Cancelled</strong> (`subscriptions.cancelled`) — This subscription has been cancelled</li>
          <li><strong>Subscription Finished</strong> (`subscriptions.finished`) — This subscription has finished</li>
          <li><strong>Subscription Paused</strong> (`subscriptions.paused`) — This subscription has been paused</li>
          <li><strong>Subscription Resumed</strong> (`subscriptions.resumed`) — This subscription was resumed</li>
        </ul>
      </div>
    </Step>

    <Step title="Instalment schedule events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for instalment schedules.</p>

        <ul>
          <li><strong>Instalment Schedule Created</strong> (`instalment_schedules.created`) — The instalment schedule has been created</li>
          <li><strong>Instalment Schedule Cancelled</strong> (`instalment_schedules.cancelled`) — The instalment schedule has been cancelled</li>
          <li><strong>Instalment Schedule Errored</strong> (`instalment_schedules.errored`) — One or more instalments in this instalment schedule failed to collect successfully</li>
          <li><strong>Instalment Schedule Completed</strong> (`instalment_schedules.completed`) — This instalment schedule has concluded</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery format</h2>

  <p>Details of how GoCardless delivers events to StackOne.</p>

  <Steps>
    <Step title="Batched payloads">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Each request carries an `events` array and can contain several events at once. StackOne splits every request and routes each event on its own by its `resource_type` and `action`, so no event in a batch is lost. The event data is that single GoCardless event.</p>
      </div>
    </Step>

    <Step title="Retries and ordering">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>GoCardless retries a delivery that does not receive a 2xx response, up to 9 attempts in total, and may deliver the same event more than once or out of order. StackOne acknowledges event types it does not map so that GoCardless does not retry them.</p>
      </div>
    </Step>

    <Step title="Signatures">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>GoCardless signs each request with an HMAC SHA256 digest of the body in the `Webhook-Signature` header, using the endpoint's secret. You can review every delivery attempt under <strong>Developers</strong> > <strong>API settings</strong> > <strong>Webhooks</strong> in the GoCardless dashboard.</p>
      </div>
    </Step>
  </Steps>
</section>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.