# Receiving Events - Webhooks

When new messages come into any of your channels or you want to be notified immediately we have any updates on your conversations, we trigger events that your application can listen to. We do this using webhooks.

A webhook is a URL on your server where we send payloads for such events.

You can specify your webhook URL on your [Settings page](https://app.oneroute.io/settings/account-settings) or on individual channels where we would send `POST` requests to whenever an event occurs.

{% hint style="info" %}
Kindly ensure your webhook URL is publicly available (localhost URLs cannot receive events).
{% endhint %}

### Verify Event Origin

#### Signature

Our event comes with \`\`\`x-oneroute-signature\`\`\` in the header and you can use this to verify the event is from us and wasn't tampered with. To verify the origin, you can use the below code

```
const oneRouteSignatureHash = req.headers['x-oneroute-signature']
const hash = crypto.createHmac('sha512', 'OneRoute Secret Key').update(JSON.stringify(req.body)).digest('hex');

if (oneRouteSignatureHash === hash) {
    // valid... do something
} else {
    // invalid...  do something
}
```

#### IP whitelisting <a href="#ip-whitelisting" id="ip-whitelisting"></a>

With this method, you only allow certain IP addresses to access your webhook URL while blocking out others. OneRoute will only send webhooks from the following IP addresses:

1. 174.138.104.128

### Receiving Events

To receive the event, you will have to create an unauthenticated `POST` route on your application that returns a <mark style="color:green;background-color:blue;">`200`</mark> status code as it's response.

{% tabs %}
{% tab title="Node" %}

```
// Using Express
app.post("/my/webhook/url", function(req, res) {
    // Retrieve the request's body
    var event = req.body;
    // Do something with event
    res.send(200);
});
```

{% endtab %}

{% tab title="PHP" %}

```
<?php
// Retrieve the request's body and parse it as JSON
$input = @file_get_contents("php://input");
$event = json_decode($input);
// Do something with $event
http_response_code(200); // PHP 5.4 or greater
?>
```

{% endtab %}
{% endtabs %}

### Supported Events

{% tabs %}
{% tab title="New Incoming Message" %}

```json
{
  "event": "newMessage",
  "message": {
    "sender": {
      "name": "Message Sender",
      "authUser": false,
      "lastActivity": "2022-01-29T07:27:52.676Z"
    },
    "externalId": null,
    "content": "Hello World!",
    "contentType": "TEXT",
    "imageUrl": null,
    "videoUrl": null,
    "documentUrl": null,
    "audioUrl": null,
    "quoted_message_id": null,
    "conversation_id": "bf9d96d9-e495-489a-a22a-206b0ea44d90"
  },
  "conversation": {
    "id": "bf9d96d9-e495-489a-a22a-206b0ea44d90",
    "subject": null,
    "agent": null,
    "customer": {
      "name": "Customer name",
      "email": "customer@mail.com"
    },
    "lastMessageAt": "2022-01-29T07:27:52.793Z",
    "status": "in-queue",
    "country": "NG",
    "read": false,
    "createdAt": "2022-01-29T07:18:58.172Z",
    "updatedAt": "2022-01-29T07:27:52.794Z",
    "agent_id": null,
    "Channel": {
      "id": "8bad2edc-2973-4cec-8f33-a17c54dc0686",
      "phone": null,
      "identifier": "Identifier",
      "medium": "WHATSAPP",
      "credentials": null,
      "description": "Whatsapp Channel",
      "name": "Channel name",
      "type": "CUSTOM",
      "provider": null,
      "country": "NG",
      "env": "LIVE",
      "status": "ACTIVE",
      "webhookUrl": "https://webhook.url"
    }
  }
}
```

{% endtab %}

{% tab title="Low Balance Notification" %}

```json
{
    "event": "lowUnitBalance",
    "firm": "Firm Name",
    "units": 0 // remaining unit balance
}
```

{% endtab %}

{% tab title="OTP Verified" %}

```json
{
    "event": "otpVerified",
    "id": "12345678904",
    "otp": "12345",
    "identifier": "key",
    "expiration_time": "2022-01-29T07:27:52.676Z",
    "createdAt": "2022-01-22T07:27:52.676Z",
    "verified": true
}
```

{% endtab %}

{% tab title="SMS Delivery Report" %}

```json
{
    "event": "smsDeliveryReport",
    "message": null,
    "conversation": {
        "id": "1234567",
        "externalId": "1234567890",
        "status": "delivered",
        "reason": "Message delivered to handset",
        "from": "Name",
        "to": "12345678",
        "units": 0,
        "delivered_time": "2023-08-29T08:18:31.732Z",
        "createdAt": "2023-08-29T08:18:28.576Z"
    }
}
```

{% endtab %}

{% tab title="Whatsapp Delivery Report" %}

```json
{
    "event": "whatsappDeliveryReport",
    "message": null,
    "conversation": {
        "id": "iodsjiohsduihys7ywwy8oisd",
        "externalId": "iusdiywy78wt6stfauahiu",
        "status": "read",
        "reason": null,
        "from": "23480xxxxxxxx",
        "to": "+23480xxxxxxxx",
        "units": 0,
        "delivered_time": "2024-12-04T13:49:05.000Z",
        "template_category": "MARKETING",
        "createdAt": "2024-12-04T13:47:23.000Z",
        "campaign_id": null,
        "identifier": null
    }
}
```

{% endtab %}
{% endtabs %}

### WhatsApp Campaign Events

{% tabs %}
{% tab title="Campaign Completed " %}

```json
{
    "event": "compaignDeliveryReport",
    "message": "campaign completed.",
    "campaignReportUrl": "https://api.oneroute.io/api/public/logs?page[size]=10&page[number]=1&campaign_id=campaign_id"
    "conversation": {
        "id": "id",
        "firm_id": "firm id"
    }
}
```

{% endtab %}

{% tab title="Campaign Message DLR" %}

```json
{
    "event": "whatsappDeliveryReport",
    "message": null,
    "conversation": {
        "id": "iodsjiohsduihys7ywwy8oisd",
        "externalId": "iusdiywy78wt6stfauahiu",
        "status": "read",
        "reason": null,
        "from": "234879927352",
        "to": "+23480634279362",
        "units": 0,
        "delivered_time": "2024-12-04T13:49:05.000Z",
        "template_category": "MARKETING",
        "createdAt": "2024-12-04T13:47:23.000Z",
        "campaign_id": "982376327jiadnkjddxtdd",
        "identifier": "f1005383-7d8d-4351"
    }
}
```

{% endtab %}

{% tab title="Campaign Report Sample" %}

```json
{
    "count": 2,
    "data": [
        {
            "id": "uiwyytw8728928ujd",
            "externalId": "isjdoijui87w6e7iousiojiosdus",
            "status": "read",
            "reason": null,
            "from": "2348183625392",
            "to": "+234808376725898",
            "units": 0,
            "delivered_time": "2024-12-04T13:49:05.000Z",
            "createdAt": "2024-12-04T13:47:23.000Z",
            "campaign_id": "8932789ujksdmkiosuydw78",
            "identifier": "f1005383-7d8d-4351"
        },
        ...
    ],
    "currentPage": 1,
    "totalPage": 1,
    "message": "logs data",
    "success": true
}
```

{% endtab %}
{% endtabs %}