# fbm-webhook

> Facebook Messenger webhook middleware for Express.

Latest version **1.0.4** (published 2018-12-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install fbm-webhook
pnpm add fbm-webhook
yarn add fbm-webhook
bun add fbm-webhook
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.4 |
| Published | 2018-12-07 |
| First published | 2018-11-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=8.0.0 |
| Dependencies | 4 |
| Unpacked size | 15.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Risan Bagja Pradana |
| Maintainers | risan |
| Keywords | facebook, messenger, webhook |

## Links

- npm: https://www.npmjs.com/package/fbm-webhook
- Repository: https://github.com/risan/fbm-webhook
- Issues: https://github.com/risan/fbm-webhook/issues
- npm.io page: https://npm.io/package/fbm-webhook

## Dependencies (4)

- [express](https://npm.io/package/express.md) 4.x
- [lodash.get](https://npm.io/package/lodash.get.md) 4.x
- [lodash.has](https://npm.io/package/lodash.has.md) 4.x
- [body-parser](https://npm.io/package/body-parser.md) 1.x

## Recent versions

- 1.0.4 (latest) — 2018-12-07
- 1.0.3 — 2018-12-02
- 1.0.2 — 2018-11-24
- 1.0.1 — 2018-11-18
- 1.0.0 — 2018-11-14
- 1.0.0-alpha.1 — 2018-11-11

## README

# Facebook Messenger Webhook

[![Build Status](https://badgen.net/travis/risan/fbm-webhook)](https://travis-ci.org/risan/fbm-webhook)
[![Test Covarage](https://badgen.net/codecov/c/github/risan/fbm-webhook)](https://codecov.io/gh/risan/fbm-webhook)
[![Greenkeeper](https://badges.greenkeeper.io/risan/fbm-webhook.svg)](https://greenkeeper.io)
[![Latest Version](https://badgen.net/npm/v/fbm-webhook)](https://www.npmjs.com/package/fbm-webhook)

Facebook Messenger webhook middleware for Express.

## Installation

```bash
$ npm install fbm-webhook
```

## Usage

Add `fbm-webhook` middleware into your existing Express app:

```js
const express = require("express");
const fbmWebhook = require("fbm-webhook");

const app = express();
const webhook = fbmWebhook({
  appSecret: "Your Facebook App Secret",
  verifyToken: "Your Predefined Verify Token"
});

app.use("/webhook", webhook);

// Listen to the message received event.
webhook.on("message", event => {
  console.log(`Sender id: ${event.sender.id}`);
  console.log(`Message: ${event.message}`);
});

// Listen to the message read event.
webhook.on("read", event => console.log(event));

app.listen(3000, () => console.log("Server is running on port: 3000"));
```

The `fbm-webhook` middleware will register two endpoints:

* `GET /webhook`: For webhook URL verification.
* `POST /webhook`: The actual webhook that will receive events data from the Facebook Messenger.

The `verifyToken` is your own predefined secret. It's the one that will be used by Facebook to verify your webhook URL.

Check all supported [webhook events](#webhook-events).

## Recipes

### Store App Secret and Verify Token as Environment Variables

By default, `fbm-webhook` will look for `FB_APP_SECRET` and `FB_VERIFY_TOKEN` on the environment variables. If you set these environment variable, you don't have to pass anything:

```js
const fbmWebhook = require("fbm-webhook");

const webhook = fbmWebhook();

// Is equal to
const webhook = fbmWebhook({
  appSecret = process.env.FB_APP_SECRET,
  verifyToken = process.env.FB_VERIFY_TOKEN
});
```

And if you use another name:

```js
const fbmWebhook = require("fbm-webhook");

const webhook = fbmWebhook({
  appSecret = process.env.MY_APP_SECRET,
  verifyToken: process.env.MY_VERIFY_TOKEN
});
```

### Use Different Endpoints

```js
const express = require("express");
const fbmWebhook = require("fbm-webhook");

const app = express();
const webhook = fbmWebhook();

app.use("/foobar", webhook);
```

Your webhook endpoints will be:

* `GET /foobar`: For webhook verification.
* `POST /foobar`: The actual webhook handler.

### Listen to All Types of Event

```js
const express = require("express");
const fbmWebhook = require("fbm-webhook");

const app = express();
const webhook = fbmWebhook();

app.use("/webhook", webhook);

// Listen to all types of event.
webhook.on("data", event => console.log(event));

app.listen(3000, () => console.log("Server is running on port: 3000"));
```

### Disable Request Signature Verification

By default, `fbm-webhook` will look for the `X-Hub-Signature` header on all incoming webhook. It will verify this request signature using your `appSecret`. You can disable this verification process by passing a false value to `appSecret` (it's not recommended though).

```js
const fbmWebhook = require("fbm-webhook");

const webhook = fbmWebhook({ appSecret: false });
```

### Run as Standalone Express Application

You can instantiate `fbm-webhook` as an Express application too:

```js
const fbmWebhook = require("fbm-webhook");

const webhook = fbmWebhook({ path: "/webhook" });

// Listen to the message received event.
webhook.on("message", event => {
  console.log(`Sender id: ${event.sender.id}`);
  console.log(`Message: ${event.message}`);
});

webhook.listen(3000, () => console.log("Server is running on port: 3000"));
```

## Webhook Events

| Event Type | Messenger Subscription Field | Documentation |
| -- | -- | -- |
| `message` | `messages` | [Message recevied events](https://developers.facebook.com/docs/messenger-platform/webhook-reference/message-received) |
| `echo` | `message_echoes` | [Message Echo events](https://developers.facebook.com/docs/messenger-platform/webhook-reference/message-echo) |
| `account-linking` | `messaging_account_linking` | [Account Linking events](https://developers.facebook.com/docs/messenger-platform/webhook-reference/account-linking) |
| `checkout-update` | `messaging_checkout_updates` | [Checkout Update events](https://developers.facebook.com/docs/messenger-platform/webhook-reference/checkout-update) |
| `delivered` | `message_deliveries` | [Message Delivered events](https://developers.facebook.com/docs/messenger-platform/webhook-reference/message-delivered) |
| `game-play` | `messaging_game_plays` | [Instant Game events](https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_game_plays/) |
| `optin` | `messaging_optins` | [Plugin Opt-in events](https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_optins) |
| `payment` | `messaging_payments` | [Payment events](https://developers.facebook.com/docs/messenger-platform/webhook-reference/payment) |
| `policy-enforcement` | `messaging_policy_enforcement` | [Policy Enforcement events](https://developers.facebook.com/docs/messenger-platform/webhook-reference/policy-enforcement) |
| `postback` | `messaging_postbacks` | [Postback Received events](https://developers.facebook.com/docs/messenger-platform/webhook-reference/postback-received) |
| `pre-checkout` | `messaging_pre_checkouts` | [Payment Pre-checkout events](https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_pre_checkouts) |
| `read` | `message_reads` | [Message Read events](https://developers.facebook.com/docs/messenger-platform/webhook-reference/message-read) |
| `referral` | `messaging_referrals` | [Referral events](https://developers.facebook.com/docs/messenger-platform/webhook-reference/referral) |
| `standby` | `standby` | [Handover Protocol Standby Channel events](https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/standby) |
| `handover.app-roles` | `messaging_handovers` | [Handover Protocol assign app roles events](https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_handovers#app_roles) |
| `handover.pass-thread-control` | `messaging_handovers` | [Handover Protocol pass thread control events](https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_handovers#pass_thread_control) |
| `handover.take-thread-control` | `messaging_handovers` | [Handover Protocol take thread control events](https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_handovers#take_thread_control) |
| `handover.request-thread-control` | `messaging_handovers` | [Handover Protocol request thread control events](https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_handovers#request_thread_control) |
| `unknown` | | Other event types not listed above |
| `data` | | Listen to all type of events |

## API

### `fbmWebhook`

```js
fbmWebhook([{
  path = "/",
  appSecret = process.env.FB_APP_SECRET,
  verifyToken = process.env.FB_VERIFY_TOKEN
}])
```

#### Parameters

* `path` (optional `String`): The webhook route prefix, default to `/`.
* `appSecret` (optional `String`): Your Facebook App Secret, default to `process.env.FB_APP_SECRET`.
* `verifyToken` (optional `String`): Your own predefined verify token. Used by Facebook to verify webhook URL, default to `process.env.FB_VERIFY_TOKEN`.

#### Return

It returns an [Express application](https://expressjs.com/en/4x/api.html#app) instance.

### `fbmWebhook.on`

Listen to a webhook event.

```js
fbmWebhook.on(eventType, callback);
```

#### Parameters

* `eventType` (`String`): The [webhook event](#webhook-events) to listen to.
* `callback` (`Function`): The callback function to call, it will receive the `event` payload sent by the Messenger platform.

## Related

* [fbm-send](https://github.com/risan/fbm-send): Module for sending message through Facebook Messenger Send API.

## License

[MIT](https://github.com/risan/fbm-webhook/blob/master/LICENSE) © [Risan Bagja Pradana](https://bagja.net)

## Legal

This code is in no way affiliated with, authorized, maintained, sponsored or endorsed by [Facebook](https://facebook.com) or any of its affiliates or subsidiaries. This is an independent and unofficial API.

---
_Source: https://npm.io/package/fbm-webhook · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._