---
title: Overview
slug: connect/lqUr-overview
docTags: 
createdAt: 2023-12-05T09:33:30.529Z
---

Webhook events are sent during a Link session as the end user interacts with the application. You can track progress through this session (`linkId`), get information about end user usage, and receive notifications when certain processes are complete.

Whether you integrate through WhiteLabel or API Only, some API statuses will also be sent to you via webhook.

:::hint{type="info"}
You can also choose to turn off or turn on the above two types of webhooks in the [Console](https://console.klavi.ai).
Only when enabled, will you be asked to configure a webhook address and send corresponding the event to the webhook.
:::

# How to use webhook

## Register

When you are ready to go live and move your application to production, you can obtain the `accessKey` and `secretKey` for production environment through Klavi business personnel ([suporte@klavi.ai](mailto\:suporte@klavi.ai)) or [Klavi console](https://console.klavi.ai), and set your webhook URL. 

Klavi defaults to using the `secretkey` and **SHA-256 HMAC** algorithm to sign the payload.

## Retry logic

If we get a 2xx response from your webhook listener server, the webhook event is registered as a success. For any non-200 HTTP status code (failed event), we will resend the webhook.

Default retries configurations:

- **Timeout: **10s
- **Retries: **5
- **Backoff for automatic retries: **250ms Exponential
- **Max redirects: **3

## Payloads

The following parameter will be included in the request **header** that Klavi `POST` to you.

### Headers

```none
x-klavi-signature: 'webhook-hmac-hash'
x-klavi-timestamp: '123456789012'
```

We recommend that you verify the signature of the webhook. For more detail, please refer to the [Security](docId\:Dg06Bf5lVYsFyhpEMWos0).

### Event body

| **Name**     | **Description**                                                                                                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| partnerAppId | Unique identifier for partner                                                                                                                                                          |
| eventId      | Unique identifier for the event                                                                                                                                                        |
| eventType    | `api`: All events related to API call                                                                                                                                                  |
| eventName    | The name of each event                                                                                                                                                                 |
| eventTime    | The time when this event was triggered(UTC timezone)                                                                                                                                   |
| payload      | All events include a wrapper that contains metadata. The event data is within the this key, different events result in different payload contents.                                     |
| externalInfo | If you specified custom events via the `externalInfo` parameter when generating a `links`, you will receive the object (`externalInfo`) back in the body for all other link event type |

**Example:** Pass the `externalInfo` object in a generate `links` call to receive the started event notification.

```json
"externalInfo": {
  "myCustomerId": "123456789",
  "myRequestId": "234567890"
}
```

After the link is successfully created, the parameters you pass will be returned to you through webhook.

In order to improve the system performance of both parties, Payload uses array objects, which means multiple events may be merged into one JSON and sent to you.

```json
[
    {
        "partnerApp":"12345678",
        "eventId":"1495468585434-0e73d1719173766fe4dfe1a8",
        "eventType":"api",
        "eventName":"link-created",
        "eventTime":"2021-05-21T08:30:00Z",
        "payload":{
            "linkId":"ed812-81fcec-7ec55-7aa7d29-2a3188b75"
        },
        "externalInfo":{
            "myCustomerId":"12345678",
            "myRequestId":"23456789"
        }
    }
]
```