> **Description:** Implement real-time payment notifications with webhook endpoints and event handling.

# Webhooks

You can receive instant notifications about important events, such as successful payments and cancellations.
To set up the basic webhook infrastructure, you need to register your webhook URL, as described in the [Webhooks API guide](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/api-guide.md).
We'll send the real-time notifications about subscription events to the URL you specify.

The ePayment events include:

| Name       | Event Type                        |
| ---------- | --------------------------------- |
| Created    | `epayments.payment.created.v1`    |
| Aborted    | `epayments.payment.aborted.v1`    |
| Expired    | `epayments.payment.expired.v1`    |
| Cancelled  | `epayments.payment.cancelled.v1`  |
| Captured   | `epayments.payment.captured.v1`   |
| Refunded   | `epayments.payment.refunded.v1`   |
| Authorized | `epayments.payment.authorized.v1` |
| Terminated | `epayments.payment.terminated.v1` |

**INFO**

To get webhooks for these events, the payment must be initiated in ePayment API.

## Create a webhook

Register to get a webhook when we create a payment.
This is the [`epayments.payment.created.v1`](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/events.md#epayment-api-event-types) event.

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.

```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"]
}'
```

You will receive a response similar to this, confirming that the webhook registration was successful:

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

We support up to 25 webhook registrations per event type per MSN.
For more about these limits,
see [webhook limits](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/api-guide.md#webhook-limits).

**Please note**

Webhooks offer a faster user experience than polling, but you
should not rely on webhooks alone.
In the rare cases where webhooks may be delayed, you should poll the relevant
API to get the information you need:
[`GET:/epayment/v1/payments/{reference}`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml).

Depending on your use case, you should set an appropriate timeout for webhooks.
If the webhook is not received within that time, you should start polling.

Please follow our [polling guidelines](https://developer.vippsmobilepay.com/docs/knowledge-base/polling-guidelines.md).

## Webhook payload

For any webhook, you will receive the following payload, where the only property changing is
the `name`, which will reflect the event type you subscribed to.

Additional information:

* `idempotencyKey` is not required, and some webhooks (e.g., `CANCELLED`) may not supply this value.
* The `pspReference` is different for API responses versus webhook notifications (see [Understanding `pspReference`](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/concepts.md#understanding-pspreference)).
* Profile information in webhooks -
    If you [requested profile information](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/profile-sharing.md) in the payment, the `userDetails` and `profile.sub` fields are included in the `epayments.payment.authorized.v1` webhook payload automatically.
* The webhooks described here are not applicable to the eCom API.

## For more information

For more information about webhooks, see:

* [Webhook API spec](https://developer.vippsmobilepay.com/redocusaurus/webhooks-swagger-id.yaml)
* [Full list of Webhooks events](https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/events.md)

> **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).