# flexEngage Webhooks Integration Guide

This guide shows you how to use webhooks to receive event notifications for various flexEngage services.

Webhooks allow you to subscribe to event notifications via an HTTPS callback. When an event occurs, flexEngage 
dispatches the event to the HTTPS endpoints you have configured.

At a high-level, in order to use webhooks, you must:

1. Create an HTTPS endpoint(s) to receive the events published via webhook.
1. Create subscriptions that register your HTTPS endpoint(s) as callbacks for the types of events you wish to be notified.

##  Webhook Events

A variety of events are published via webhooks but, they all share the following common underlying structure: 

```json
{
  "id": "01F2SFVYVD0H873S2VRT8VQSPM",
  "brandId": "yourBrandId",
  "webhookId": "9e21c694-ee9e-48a7-b016-522fd8ef08c1",
  "attemptId": "01F2SFW32CT8KZXDWG4JTG9WPT",
  "created": "2021-04-08T19:36:02.938Z",
  "type": "NOTIFICATION.SMS.RECEIPT",
  "data": { ... }
}
```

* `id` - this is a unique identifier for the event.
* `brandId` - this is your account identifier.
* `webhookId` - this is the id of the webhook that published the event.
* `attemptId` - this uniquely identifies the attempt to your HTTPS endpoint. An event can be retried up to 
1 hour if we are unable to deliver it to your HTTPS endpoint.
* `created` - when the event was created.
* `type` - the type of event published.
* `data` - this is data specific to the actual event.


__NOTE:__ Notifications are not enabled by default. Please work with your [support team](mailto:support@flexengage.com) 
to enable notifications for the events you are interested in.


### The `type` Attribute

Every event published via webhook has a `type` attribute that describes what the event is. 

You can find the full list of supported event types here: [Supported Event Types](/webhooks/supported-event-types.html).

## Creating Subscriptions

When you create a webhook, you must specify:

* The type of events you want to receive.
* An HTTPS endpoint for receiving the event.

The following webhook creation request will listen to all sms receipt events:

```json
{
  "endpoint": "https://example.com/my/webhook/endpoint",
  "events": [
    "NOTIFICATION.SMS.RECEIPT"
  ],
  "enabled": true
}
```

## Endpoint Development Guidelines

This section outlines guidelines for building your endpoint for receiving event notifications.

### Supported Protocols

All endpoints must support the HTTPS protocol. If you try to create a webhook with an HTTP address, you will receive 
an error response (HTTP status 422) indicating this constraint.

### Authentication

Webhooks may be authenticated using [Signature Verification](signature-verification.html). At a high-level, each
request sent to your endpoint contains headers that you can use to validate the request came from our system.

### Endpoint Failures

If your endpoint responds with an error, we will attempt to re-deliver the event for up to an hour. If you are not able to 
process the event within the hour, you can use the [Get Events API](/#get-/v1/-brandId-/webhooks/-id-/events) to retrieve all events 
for a webhook within a given timeframe. All events will remain available via this API for up to 7 days.

### Unresponsive Webhooks

If your webhook endpoint is unresponsive or returns HTTPS error codes at a high rate, we 
may disable your webhook (but not delete it). Our support team will reach out to your point of contact 
before it can be re-enabled.

### Exactly Once Processing Not Guaranteed

We do not guarantee an event will be published exactly once. As such, your endpoint must be idempotent and ignore
duplicate events. You can use the `id` attribute of an event published via webhook to determine if you have already 
processed an event.