> **Description:** Step-by-step guide to quickly set up and test webhook notifications, with examples for endpoint configuration and event handling.

> **AI agent:** Read [https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md](https://developer.vippsmobilepay.com/docs/knowledge-base/ai-tools.md) first. It covers keeping API keys and secrets out of generated code.

> **Full site overview:** For an overview of the entire site, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).

# Quick start

This guide walks you through registering webhooks.

If you're new to the platform, see
[Integration quick start guide](https://developer.vippsmobilepay.com/docs/getting-started.md)
for information about API keys, product activation, and the test environment.

## With sales unit or partner keys

Follow these steps if you authenticate with sales unit API keys or partner keys.
If you have merchant-level keys for Donations, follow
[With Donations merchant-level keys](#with-donations-merchant-level-keys) instead.

### Step 1 - Setup

You will need the following values from your [sales unit API keys](https://developer.vippsmobilepay.com/docs/knowledge-base/portal.md#how-to-find-the-api-keys):

* `client_id` - Client ID for a sales unit.
* `client_secret` - Client secret for a sales unit.
* `Ocp-Apim-Subscription-Key` - Subscription key for a sales unit.
* `Merchant-Serial-Number` - The unique ID for a sales unit (required for partners and PSPs).

Replace all example values in this guide with the values for your sales unit and user.
This applies to API keys, HTTP headers, references, and phone numbers.

#### API client

Download the following files. They are in the
[Postman collection format](https://developer.vippsmobilepay.com/docs/knowledge-base/api-collections.md), so you can use them in Postman or import them
into another API client.

Update the environment with your own values for the API keys, callback URL, and international mobile number.
*Don't store production keys in the cloud.*

* [Download Webhooks API collection](https://developer.vippsmobilepay.com/tools/Webhooks.postman_collection.json)
* [Download global environment](https://developer.vippsmobilepay.com/tools/global-postman-environment.json)

**TIP**

If you are using Bruno with multiple environments together, you may see conflicts and strange behavior. To avoid this,
import your environment file into each collection, instead of using it as a global environment.

#### curl

No setup is needed. Continue to [Step 2](#step-2---get-an-access-token).

### Step 2 - Get an access token

All the API endpoints require that you first obtain an API token.
Get an access token with
[`POST:/accesstoken/get`](https://developer.vippsmobilepay.com/redocusaurus/access-token-swagger-id.yaml).

#### API client

```text
Send request "Get Access Token"
```

#### curl

```bash
curl -X POST 'https://apitest.vipps.no/accesstoken/get' \
-H "Content-Type: application/json" \
-H 'client_id: YOUR-CLIENT-ID' \
-H 'client_secret: YOUR-CLIENT-SECRET' \
-H 'Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY' \
-H 'Merchant-Serial-Number: YOUR-MSN' \
--data ''
```

In production, include all `Vipps-System` headers to aid debugging.
See [HTTP headers](https://developer.vippsmobilepay.com/docs/knowledge-base/http-headers.md) for details.

Use the `access_token` value as the Bearer token in the `Authorization` header for all subsequent API requests.

### Step 3 - Register a webhook

Register a webhook for the payment created event:
[`epayments.payment.created.v1`](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/events.md#epayment-api-event-types).

For a complete list of event types, see [events](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/events.md).

For the callback URL, use your webhook server address.

#### API client

```text
Send request "Register"
```

#### curl

```bash
curl -X POST https://apitest.vipps.no/webhooks/v1/webhooks \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
--data '{
    "url": "YOUR-CALLBACK-URL",
    "events": ["epayments.payment.created.v1"]
}'
```

A successful registration returns a response like this:

```json
{
   "id":"497f6eca-6276-4993-bfeb-53cbbbba6f08",
   "secret":"090a478d-37ff-4e77-970e-d457aeb26a3a"
}
```

You can verify your webhook registration with [`GET:/webhooks/v1/webhooks`](https://developer.vippsmobilepay.com/redocusaurus/webhooks-swagger-id.yaml).

#### API client

```text
Send request "Get All"
```

#### curl

```bash
curl -X GET https://apitest.vipps.no/webhooks/v1/webhooks \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
--data ''
```

The response looks like this:

```json
{
  "webhooks": [
    {
      "id": "25f48471-6ac7-4df9-81b2-e239540b7566",
          "url": "YOUR-CALLBACK-URL",
          "events": [
              "epayments.payment.created.v1"
          ]
    }
  ]
}
```

### Step 4 - Trigger an event

Initiate a payment with: [`POST:/epayment/v1/payments`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml).
See [Create payment](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/operations/create.md) for details.

#### API client

```text
Send request "Create payment - Web redirect"
```

#### curl

```bash
curl -X POST https://apitest.vipps.no/epayment/v1/payments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H 'Idempotency-Key: YOUR-IDEMPOTENCY-KEY' \
-d '{
  "amount": {
    "currency": "NOK",
    "value": 49900
  },
  "paymentMethod": {
    "type": "WALLET"
  },
  "customer": {
    "phoneNumber": "YOUR-PHONE"
  },
  "reference": "acme-shop-123-order123abc",
  "returnUrl": "https://yourwebsite.com/redirect?reference=abcc123",
  "userFlow": "WEB_REDIRECT",
  "paymentDescription": "One pair of socks"
}'
```

### Step 5 - View the webhook

Your webhook server should receive a `POST` event with content similar to this:

```json
{
  "msn": "123456",
  "reference": "acme-shop-123-order123abc",
  "pspReference": "dd8e0a8e-2b26-40ed-98f1-1d5832fc129f",
  "name": "CREATED",
  "amount": {
    "currency": "NOK",
    "value": 49900
  },
  "timestamp": "2026-01-19T16:26:32.099Z",
  "idempotencyKey": "7c8b81e7-b08b-46e4-9729-191cb801c132",
  "success": true
}
```

This matches the payload format for the
[ePayment API events](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/events.md#epayment-api-event-types).

In production, validate the webhook to ensure the content hasn't been tampered with.
See [How to authenticate the webhook event](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/request-authentication.md) for details.

## With Donations merchant-level keys

### Step 1 - Setup and get an access token

You will need the following values from your [merchant-level keys](https://developer.vippsmobilepay.com/docs/APIs/donations-api/api-guide.md#how-to-get-the-api-keys):

* `client_id` - Client ID from your merchant-level keys.
* `client_secret` - Client secret from your merchant-level keys.

See [Donations API guide](https://developer.vippsmobilepay.com/docs/APIs/donations-api/api-guide.md) for step-by-step instructions on requesting an access token.

Use the `access_token` value as the Bearer token in the `Authorization` header for all subsequent API requests.

### Step 2 - Register a webhook

Register a webhook for the payment created event:
[`epayments.payment.created.v1`](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/events.md#epayment-api-event-types).

For the callback URL, use your webhook server address.

```bash
curl -X POST https://apitest.vipps.no/webhooks/v1/webhooks \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
--data '{
    "url": "YOUR-CALLBACK-URL",
    "events": ["epayments.payment.created.v1"]
}'
```

You can verify your webhook registration with [`GET:/webhooks/v1/webhooks`](https://developer.vippsmobilepay.com/redocusaurus/webhooks-swagger-id.yaml).

```bash
curl -X GET https://apitest.vipps.no/webhooks/v1/webhooks \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
--data ''
```

### Step 3 - Trigger an event

Initiate a payment with: [`POST:/epayment/v1/payments`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml).

```bash
curl -X POST https://apitest.vipps.no/epayment/v1/payments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H 'Idempotency-Key: YOUR-IDEMPOTENCY-KEY' \
-d '{
  "amount": {
    "currency": "NOK",
    "value": 49900
  },
  "paymentMethod": {
    "type": "WALLET"
  },
  "customer": {
    "phoneNumber": "YOUR-PHONE"
  },
  "reference": "acme-shop-123-order123abc",
  "returnUrl": "https://yourwebsite.com/redirect?reference=abcc123",
  "userFlow": "WEB_REDIRECT",
  "paymentDescription": "One pair of socks"
}'
```

### Step 4 - View the webhook

Your webhook server should receive a `POST` event like the one in
[Step 5 - View the webhook](#step-5---view-the-webhook).

In production, validate the webhook to ensure the content hasn't been tampered with.
See [How to authenticate the webhook event](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/request-authentication.md) for details.