# Webhooks

Found Hero uses webhooks to notify your application when the status of the lost item changes. You can subscribe to our webhooks to receive important updates related to your lost items.

### Setting up webhooks

To subscribe to Found Hero webhooks, follow the following steps:

1. Create a webhook endpoint at your server.
2. [Login](https://app.joinfoundhero.com/login) to your Found Hero account.
3. Go to the [account settings](https://demo.joinfoundhero.com/dashboard/settings#webhooks) page and then open the "Webhooks" tab.
4. Register the webhook endpoint with Found Hero.
5. By ready to receive notifications.

{% hint style="warning" %}
When you register a webhook endpoint, Found Hero sends an HTTP POST request to the URL to verify if it is valid. For a valid webhook URL, Found Hero expects HTTP 200 status code.
{% endhint %}

### Event types

At the moment, Found Hero supports the following events:

| Event            | Description                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `pickup`         | This event is sent when the owner chooses to pick up the lost item by himself.                                    |
| `discard`        | This event is sent when the owner decides to leave the lost item behind.                                          |
| `donate`         | This event is sent when the owner asks to donate the lost item to a charity of your own choice.                   |
| `shipping-label` | This event is sent when the owner pays the shipping fees to get the lost item back.                               |
| `request`        | This event is sent when a user creates a lost item request and claim that he lost an item in a specific location. |

### Receiving notifications

Whenever a new event happens, Found Hero will send an HTTP POST request to the webhook URL that you have configured in your [account settings](https://demo.joinfoundhero.com/dashboard/settings#webhooks).

The `Content-Type` of the request is set to `application/json` and the body of the request is a [JSON](http://json.org/) object that has the following properties:

| Property    | Type   |          | Description                                                                                        |
| ----------- | ------ | -------- | -------------------------------------------------------------------------------------------------- |
| `eventType` | string | required | The type of event (`pickup`, `donate`, `discard`, `request`, or `shipping-label`)                  |
| `eventTime` | string | required | The date and time the event occurred in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) format. |
| `payload`   | object | required | A JSON object that contains information about the event.                                           |

The `payload` object contains the following properties:

| Property       | Type   |          | Description                                                                                                                    |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `item`         | object | required | The [lost item](https://docs.joinfoundhero.com/endpoints/items#retrieve-an-item) object                                        |
| `pickupDate`   | String | optional | The pick-up date in `YYYY-MM-DD` format. Only available for `pickup` events.                                                   |
| `pickupTime`   | String | optional | The pick-up time in `HH:mm` format. Only available for `pickup` events.                                                        |
| `shippingDate` | String | optional | Ship date in `YYYY-MM-DD` format. Only available for `shipping-label` events.                                                  |
| `serviceName`  | string | optional | The name of the courier service. Only available for `shipping-label` events.                                                   |
| `files`        | object | optional | A JSON object containing information about the shipping label and payment invoice. Only available for `shipping-label` events. |

For a typical `shipping-label` event notification, the HTTP POST request body looks like the following:

```javascript
{
    "eventType": "shipping-label",
    "eventTime": "2020-09-15T15:28:44.677Z",
    "payload": {
        "item": {/* lost item object */},
        "shippingDate": "2020-09-20",
        "serviceName": "DHL Express",
        "files": {
            "label": {
                "paper_size": "default",
                "url": "https://sandbox-download.postmen.com/label/2020-08-06/5d52b9a2-7bc7-4ac6-9201-e59144bb15ec.pdf",
                "file_type": "pdf"
            },
            "invoice": {
                "paper_size": "a4",
                "url": "https://sandbox-download.postmen.com/invoice/2020-08-06/63add3a5-2856-48d0-bab3-6e33000af393.pdf",
                "file_type": "pdf"
            }
        }
    }
}
```

Here is another example of the request body for `pickup` event notification:

```javascript
{
    "eventType": "pickup",
    "eventTime": "2020-09-15T15:28:44.677Z",
    "payload": {
        "item": {/* lost item object */},
        "pickupDate": "2020-09-15",
        "pickupTime": "14:00"
    }
}
```

### Securing webhooks

Each webhook request includes a secret signature in the `fh-signature` header. You should use this HTTP request header to verify that the events were sent by Found Hero, and not by a third-party.

You can find your own secret signature under the "Webhooks" tab of your [account settings](https://demo.joinfoundhero.com/dashboard/settings#webhooks). Make sure that you treat this signature as a secret password and never hard-code it into source control systems like Git.

### Retrying webhooks

If the webhook endpoint does not return a 200 HTTP response code, Found Hero will attempt to deliver the event again up to 5 times in increasing interval: 2^number\_of\_fail x 15s.

 For example, if the first attempt fails, Found Hero will retry the 2nd attempt after 15 seconds.

If the second attempt fails, the next attempt will be made after 60 seconds and so on.