# Webhoook Event Notification

Notifications, often referred to as webhooks, provide a mechanism for applications to receive real-time updates about specific events. Within this API, webhooks are used to inform your server about a range of events, including transactions, refunds, or card tokenization, allowing your system to react promptly to these occurrences.

{% hint style="info" %}
Notification / Webhook URL must be provided beforehand so that traffic can be allowed.
{% endhint %}

## Security

To validate the authenticity of requests, we use a signature process. The API key is hashed using SHA-256 to generate a key, which is then used in a HMAC-SHA-256 operation to sign the timestamp (Sec-Timestamp header) and request body. The signature is then compared to the value sent in the Sec-Signature header. Additionally, after verifying the signature, you must retrieve the session object to ensure the accuracy and legitimacy of the event before further processing. Note that you should expect to receive multiple events and handle each one accordingly.

```
key = SHA256(secretAPIKey)
time = request.header.Get('Sec-Timestamp')
hmac = HMAC-SHA-256(time + request.body, key)
if hmac == request.header.Get('Sec-Signature') {
    echo "Signature is valid"
}    
```

{% hint style="info" %}

## Resending of notifications

The webhook must return a status code within the 2xx range. If a different status code is received, the system will make 4 retry attempts. After the 4th attempt, it will continue retrying with an exponential backoff for up to 3 days.
{% endhint %}

## Webhoook Event Object <a href="#webhoook-event-specification" id="webhoook-event-specification"></a>

| Field               | Type   | Description                                                                                                                                                                                                |
| ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                  | string | Unique identifier for the event object.                                                                                                                                                                    |
| type                | enum   | <p>The event type is either “session.created”, “session.expired”, “session.completed”, “refund.created”, “refund.failed”, “refund.succeeded”. </p><p>Events starting with “refund.” are refund events.</p> |
| version             | string | The API version used to render the event data.                                                                                                                                                             |
| created\_at         | int    | The Unix timestamp (in seconds) when the event was created.                                                                                                                                                |
| data.status         | enum   | Present only for session events (event type starts with “session."). The status of the session. One of: “open”, “expired”, or “completed”.                                                                 |
| data.session\_id    | string | Unique identifier for the session object associated to the event. Present in both session and refund events.                                                                                               |
| data.refund\_id     | string | Present only for refund events (event type starts with “refund."). The unique identifier of the refund object associated with the event.                                                                   |
| data.refund\_status | enum   | Present only for refund events (event type starts with “refund."). The status of the refund. One of: “pending”, “succeeded”, or “failed”.                                                                  |

## Session Creation Notification

The `"session.created"` notification informs your system that a new session has been successfully created

The above event type returns JSON structured like this:

```json
{
  "id": "AZIGaeLbem2YK9tJu-hlIg",
  "version": "0.1",
  "type": "session.created",
  "create_at": 1726684455,
  "data": {
    "session_id": "AZIGaeLRdVWAenLbf0FhyA",
    "status": "open"
  }
}
```

## Session Complete Notification

The `"session.completed"` notification informs your system that a new session has been successfully completed

The above event type returns JSON structured like this:

```json
{
  "id": "AZICl7zwcWy-RRgcTH0mbQ",
  "version": "0.1",
  "type": "session.completed",
  "create_at": 1726620351,
  "data": {
    "session_id": "AZIClyFieTev7xCi6JuXBQ",
    "status": "completed"
  }
}
```

## Session Expire Notification

The `"session.expired"` notification informs your system that a new session has been expired

The above event type returns JSON structured like this:

```json
{
  "id": "AZIF2O__eJSHRFuYCX18ag",
  "version": "0.1",
  "type": "session.expired",
  "create_at": 1726674956,
  "data": {
    "session_id": "AZIF2O-zdqO1BTTr6V0opw",
    "status": "expired"
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.convergegate.com/legacy/apm-checkout-blik/webhoook-event-notification.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.