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

# Configure journey completion notifications

> Configure a notification setting so that GBG GO tells your system in real time when a journey completes, then fetch the result using the API.

In the **Settings** page, you can configure notification settings so that GBG GO tells you as soon as a journey completes. When a journey completes, GBG GO sends a signed HTTPS POST to the endpoint you configure. Your application then fetches the full result using the API.

The notification is a trigger only. It carries a reference to the completed journey but no verification data and no personal data, which keeps personal data within the platform while still giving you an immediate signal to retrieve the result.

<Note>This page covers notification settings, which GBG GO also refers to as webhooks. You configure them once in **Settings** and reuse them across journeys, and they notify you when a journey completes. To send a message from a specific point inside a journey, add a Webhook module to the journey instead. For how to use and configure a Webhook module, see [Webhook module](/docs/go-v2/guides/product-guides/webhook-module-guide).</Note>

You can create notification settings once and reuse them across multiple journeys. For how to connect a notification setting to a journey, see [Connect a notification setting to a journey](#connect-a-notification-setting-to-a-journey).

## Prerequisites

* Notification settings are enabled for your organisation. If the **Notification settings** tab is not displayed in **Settings**, contact your GBG representative.
* You are logged in to GBG GO with a role that has permission to read notification settings.

## How notifications work

<Steps>
  <Step title="A user completes a journey">
    The journey reaches its end event in GBG GO.
  </Step>

  <Step title="GBG GO sends a notification">
    GBG GO sends a signed HTTPS POST to the endpoint configured in your notification setting.
  </Step>

  <Step title="Your endpoint receives the payload">
    The payload contains a reference to the completed journey. It contains no personal data.
  </Step>

  <Step title="Your application fetches the result">
    Your application calls [Fetch journey state](/docs/go-v2/api-reference/endpoint/fetch-journey-state) with the `instanceId` from the payload to retrieve the completed journey.
  </Step>
</Steps>

## Add a notification setting

<Note>The **Notification settings** tab already contains two settings, **Default notification (Pre-production)** and **Default notification (Production)**. These are examples that show how a notification setting is structured. They point at a placeholder endpoint that does not receive notifications, so create your own setting rather than referencing a default in a start request.</Note>

To add a notification setting:

1. In GBG GO, click **Settings**.
2. Click the **Notification settings** tab.
3. Click **New setting**.
   The Add notification setting dialog is displayed.
   * **Name**: A name that identifies where the notifications are sent, for example `Fraud-ops endpoint`.
   * **Endpoint URL**: The public HTTPS endpoint that receives the notifications.
   * **Authentication**: The authentication method your endpoint requires. Select either **None**, **Basic auth**, or **API key**.
     * **None**: GBG GO sends no authentication credentials.
     * **Basic auth**: Enter the **Username** and **Password** your endpoint expects.
     * **API key**: Enter the **Key**, and the **Header name** to send it in. The header name defaults to `Authorization`. You cannot use `x-gbg-signature` or `content-type` as the header name.
4. Click **Save setting**.

The new setting is displayed in the list with its resource ID, version, and the date it was last updated.

<Note>Endpoints must be publicly reachable over HTTPS. GBG GO checks the endpoint URL when you send a test notification. Saving a setting does not check that the endpoint is reachable, so send a test notification to confirm that yours is.</Note>

<Info>Every notification is signed, whatever authentication method you select. If you select **None**, GBG GO still signs the request, so an endpoint that cannot put authentication in front of it can still confirm that a notification came from GBG GO. For how to check the signature, see [Verify a notification](#verify-a-notification).</Info>

## Connect a notification setting to a journey

A notification setting does nothing until a journey references it. To connect the two, add `context.config.notification.resource` to your start request, using the resource ID and version of the setting:

```json JSON theme={null}
{
  "resourceId": "your-journey-resourceId@latest",
  "context": {
    "config": {
      "delivery": "api",
      "notification": {
        "resource": "your-notification-resourceId@1"
      }
    }
  }
}
```

The `resource` value uses the short `resourceId@version` form, the same format as the journey `resourceId`. Use the resource ID and version shown in the list on the **Notification settings** tab. Do not use the full `grn:::` form.

| Field                                  | Required | Description                                                                                                                          |
| -------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `context.config.notification.resource` | No       | The notification setting to use, in the format `{resourceId}@{version}`. Omit this field if the journey does not send notifications. |

<Warning>If GBG GO cannot resolve a notification reference, the journey starts, runs, and completes normally, and no error is returned, but no notification is sent. If your endpoint receives nothing, check that the resource ID and version in your start request match a notification setting exactly.</Warning>

<Tip>Send a test notification after you connect the setting, to confirm that your endpoint receives and verifies it. For the steps, see [Send a test notification](#send-a-test-notification).</Tip>

## Send a test notification

You can send a test notification to check that your endpoint receives and accepts notifications before you connect the setting to a journey.

To send a test notification:

1. In GBG GO, click **Settings**.
2. Click the **Notification settings** tab.
3. On the row of the setting you want to test, click the three dots, then click **Send test**.
   The Test dialog is displayed, showing the request that GBG GO sends.
4. Review the request body and headers.
5. Click **Send test request**.

The dialog moves through the Request, Sending, and Result stages. On the Result stage, you can review what your endpoint returned in the following tabs:

* **Response**: The body your endpoint returned. If the request did not reach your endpoint, the body explains why instead.
* **Headers**: The headers your endpoint returned.
* **Request sent**: The request GBG GO sent, so that you can compare it with what your endpoint received.

If the test fails, a message at the top of the dialog explains the reason, for example that the endpoint host could not be resolved. Correct the problem, then click **Send again** to retry without leaving the dialog. Click **Close** when you are finished.

<Info>The test request uses the same shape and signature as a real completion, with test identifiers in place of real ones. The authentication header is masked in this view, and the real credential is sent only from the server.</Info>

## Edit a notification setting

To edit a notification setting:

1. In GBG GO, click **Settings**.
2. Click the **Notification settings** tab.
3. On the row of the setting you want to change, click the three dots, then click **Edit**.
   The Edit notification setting dialog is displayed.
4. Change the **Name**, **Endpoint URL**, or **Authentication** method.
5. Click **Save setting**.

Saving creates a new version of the setting with a new signing secret. The previous version keeps its own secret, and journeys that reference it are unaffected.

<Warning>Your start request keeps using the version you named in it. Until you update the start request to the new version, GBG GO keeps sending notifications to the previous endpoint and signing them with the previous secret. To apply your changes without missing notifications, follow the steps below.</Warning>

To move to the new version without missing notifications:

1. Edit the setting and click **Save setting**.
2. View the signing secret for the new version. For the steps, see [View the signing secret](#view-the-signing-secret).
3. Configure your receiving system to accept both the previous secret and the new one.
4. Update your start request to the new version.
5. Once no journeys reference the previous version, stop accepting the previous secret.

## Archive a notification setting

To archive a notification setting:

1. In GBG GO, click **Settings**.
2. Click the **Notification settings** tab.
3. On the row of the setting you want to archive, click the three dots, then click **Archive**.
   The Archive notification setting dialog is displayed.
4. Click **Archive** to confirm.

<Note>Archiving a notification removes it from notification settings. It won't appear here and can't be selected for new deliveries. Deliveries that already reference a pinned version keep working.</Note>

## Notification payload

When a journey completes, GBG GO sends the following JSON to your endpoint:

```json JSON theme={null}
{
  "schemaVersion": "1",
  "eventType": "journey.completed",
  "instanceId": "P7U7Licy40cLZiENe8MrsL",
  "status": "Completed",
  "region": "EU",
  "deliveryId": "8113f586-4c21-4f7a-9d3e-2b6f0a1c5e94",
  "idempotencyKey": "P7U7Licy40cLZiENe8MrsL:8113f586-4c21-4f7a-9d3e-2b6f0a1c5e94:journey.completed",
  "occurredAt": "2026-08-07T15:08:56.655Z"
}
```

The payload identifies the completed journey and the delivery itself. Use `instanceId` to fetch the result, and `idempotencyKey` to make sure you process each notification only once. The payload contains the following fields:

| Field            | Type   | Description                                                                   |
| ---------------- | ------ | ----------------------------------------------------------------------------- |
| `schemaVersion`  | String | The version of the notification payload schema.                               |
| `eventType`      | String | The event that triggered the notification.                                    |
| `instanceId`     | String | The unique identifier of the completed journey. Use this to fetch the result. |
| `status`         | String | The status of the journey. One of `Completed`, `InProgress`, or `Error`.      |
| `region`         | String | The region where the journey was processed.                                   |
| `deliveryId`     | String | The unique identifier of this delivery attempt. Log this for traceability.    |
| `idempotencyKey` | String | Use this to make sure you process each notification only once.                |
| `occurredAt`     | String | The date and time the journey completed, as an ISO 8601 timestamp.            |

## View the signing secret

Your receiving system uses the signing secret to verify the `X-GBG-Signature` header on incoming notifications.

To view the signing secret:

1. In GBG GO, click **Settings**.
2. Click the **Notification settings** tab.
3. On the row of the setting you want to view, click the three dots, then click **View signing secret**.
   The Signing secret dialog is displayed with the secret hidden.
4. Click the eye icon to reveal the secret, or click **Copy** to copy it to your clipboard.

## Verify a notification

Every notification includes an `X-GBG-Signature` header. The header value is the prefix `sha256=` followed by the signature as a lowercase hexadecimal digest, for example:

```bash BASH theme={null}
X-GBG-Signature: sha256=3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b
```

To verify that a notification came from GBG GO:

1. Compute the HMAC-SHA256 of the raw request body using your signing secret, and encode the digest as lowercase hexadecimal.
2. Strip the `sha256=` prefix from the `X-GBG-Signature` header to get the expected digest.
3. Compare your computed digest with the expected digest, using a constant-time comparison function.
4. Reject the request if the digests do not match.

<Warning>Compare the digests with a constant-time comparison function, such as `crypto.timingSafeEqual` in Node.js or `hmac.compare_digest` in Python. A standard string comparison returns as soon as it finds a difference, which can leak the expected signature to an attacker.</Warning>

Notifications are sent over TLS only. Each version of a notification setting has its own signing secret, and GBG GO signs with the secret that belongs to the version in your start request. For how to move to a new secret, see [Edit a notification setting](#edit-a-notification-setting).

<Warning>Always verify the signature before you process a notification. A notification that fails verification did not come from GBG GO.</Warning>

## Delivery behaviour

GBG GO makes up to three delivery attempts, waiting five seconds between each attempt. What happens after a failed attempt depends on the response:

| Response from your endpoint                              | What GBG GO does                        |
| -------------------------------------------------------- | --------------------------------------- |
| 2xx                                                      | Treats the delivery as successful.      |
| 5xx                                                      | Retries, up to the three-attempt limit. |
| No response, for example a connection or timeout failure | Retries, up to the three-attempt limit. |
| 4xx, including 429                                       | Stops. The notification is not retried. |

<Warning>GBG GO does not retry a 4xx response, including 429. If your endpoint rate-limits or rejects a notification, that notification is not delivered again. There is no dead-letter queue, so a notification that fails all three attempts is not stored for later delivery.</Warning>

Because a notification can be lost, do not rely on notifications as your only way to learn that a journey completed. Call [Fetch journey state](/docs/go-v2/api-reference/endpoint/fetch-journey-state) as a fallback, so that you still retrieve journeys whose notification never arrived. The completed journey always remains retrievable through the API.

Delivery is at least once, so your endpoint might receive the same notification more than once. Use the `idempotencyKey` to identify notifications you have already processed.

## Recommended integration pattern

To get the most reliable results, design your endpoint to:

* Accept HTTPS POST requests on a publicly reachable URL.
* Serve the notification directly at that URL, without a redirect. GBG GO does not follow redirects, so a proxy or an HTTP to HTTPS redirect in front of your endpoint stops the notification from arriving.
* Verify the `X-GBG-Signature` header before processing anything.
* Return `200 OK` within 15 seconds. GBG GO waits 15 seconds for a response before it treats the attempt as failed.
* Queue the work rather than processing it while GBG GO waits.
* Log the `deliveryId` so that you can trace a delivery.

Then, in your application:

1. Use the `idempotencyKey` to check whether you have already processed the notification.
2. Call [Fetch journey state](/docs/go-v2/api-reference/endpoint/fetch-journey-state) with the `instanceId` to retrieve the completed journey.
3. Process the result.

<Tip>Use notifications when you need to react to a completed journey immediately, for example to start a downstream workflow or update a record in another system. If you only need results periodically, fetching journey state on a schedule is simpler.</Tip>