# Events

## Introduction

Each time a given event occurs, r4nkt will notify you via a webhook. This page will list and describe the various events that can be fired.

{% hint style="warning" %}
No webhook will be called if the game's webhook URL and webhook secret properties haven't been properly set up.
{% endhint %}

## Common Payload

Each webhook will contain some common data in its payload:

* `type`: This value is used to indicate the webhook *type*.
* `date_time_utc`: This indicates the date/time for the event represented by the webhook. It will be an ISO 8601 UTC date/time representation, eg `2019-02-01T03:45:27.612584Z`.

Here is what the common elements of a sample payload might look like:

```javascript
{
    "type":"badge-earned",
    "date_time_utc":"2019-02-01T03:45:27.612584Z",
    ...
}
```

## Badge Earned

When a player earns a new badge, r4nkt will send a "badge earned" webhook. In addition to the common payload data, this webhook also includes the following:

* `custom_player_id`: The custom ID for the player that earned the badge.
* `custom_achievement_id`: The custom ID for the related achievement.
* `points`: The number of points that were allocated to the player for having earned the badge.

Here is a sample payload:

```javascript
{
    "type":"badge-earned",
    "date_time_utc":"2019-02-01T03:45:27.612584Z",
    "custom_player_id":"",
    "custom_achievement_id":"",
    "points":100
}
```

## Webhook Test

This webhook is sent from the game dashboard's webhhook settings panel and is manually initiated by any user with access. It is used to help get webhook integration up and running. In addition to the common payload data, this webhook also includes the following:

* `inspiring_quote`: This serves two purposes. First, it provides additional data so that developers have a little better idea about what to expect. Second, it can serve to inspire. 😊

Here is a sample payload:

```javascript
{
    "type":"webhook-test",
    "date_time_utc":"2019-02-01T03:45:27.612584Z",
    "inspiring_quote":"He who is contented is rich. - Laozi"
}
```

## Testing

In order to test and debug, you might like to use a service like [RequestBin.com](https://requestbin.com/) or [webhook.site](https://webhook.site/), which can show you the payload of the webhook data in real-time.


---

# 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://docs.r4nkt.com/webhooks/events.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.