# LINE Webhooks

## When to Use This Skill

* How do I receive LINE Messaging API webhooks for my LINE bot?
* How do I verify the LINE `x-line-signature` header?
* Why does my LINE webhook signature verification fail?
* Why does the **Verify** button in the LINE Developers Console fail for my webhook URL?
* How do I handle LINE `message`, `follow`, `postback` or `memberJoined` events?
* How do I dedupe redelivered LINE webhooks?

## Verification (core)

LINE signs the **raw request body** with HMAC-SHA256 keyed on your **channel secret** (Console → channel → **Basic settings**) and sends the **base64** digest in `x-line-signature`. There's no timestamp and no prefix. Verify the exact bytes received; parsing and re-serializing the JSON breaks the signature.

Node (`@line/bot-sdk`):

```javascript
const { validateSignature } = require('@line/bot-sdk');

function verifyLineSignature(rawBody, signature, channelSecret) {
  if (!signature || !channelSecret) return false;
  try {
    return validateSignature(rawBody, channelSecret, signature); // timing-safe
  } catch {
    return false;
  }
}

```

Python (`line-bot-sdk`):

```python
from linebot.v3 import SignatureValidator

def verify_line_signature(raw_body: bytes, signature: str, channel_secret: str) -> bool:
    if not signature or not channel_secret:
        return False
    # Equivalent to: base64(hmac.new(secret, raw_body, sha256).digest()) == signature
    return SignatureValidator(channel_secret).validate(raw_body.decode("utf-8"), signature)

```

No SDK? The manual version is in [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/line-webhooks/references/verification.md).

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/line-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/line-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/line-webhooks/examples/fastapi/).

**The console Verify button** sends a signed `{"destination":"U...","events":[]}`. Verify it like any other request and return `200`; an empty `events` array is valid.

## Common Event Types

One webhook request carries an `events` array; dispatch on each event's `type`:

| Event `type` | Triggered When |
| --- | --- |
| `message` | User sends a message (`message.type`: text, image, video, audio, file, location, sticker) |
| `messageEdited` | User edits a text message (group chats) |
| `unsend` | User unsends a message |
| `follow` | User adds the account as a friend, or unblocks it |
| `unfollow` | User blocks the account |
| `join` / `leave` | Account joins / leaves a group or multi-person chat |
| `memberJoined` / `memberLeft` | A user joins / leaves a group the account is in |
| `postback` | User triggers a postback action (`postback.data`) |
| `videoPlayComplete` | User finishes a tracked video message |
| `beacon` | User enters a LINE Beacon's range |
| `accountLink` | User links their LINE account to your service |
| `membership` | User joins, leaves or renews a membership |

> **For full event reference**, see [Webhook event objects](https://developers.line.biz/en/reference/messaging-api/#webhook-event-objects) and [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/line-webhooks/references/overview.md).

## Important Headers and Fields

| Header / field | Description |
| --- | --- |
| `x-line-signature` | base64 HMAC-SHA256 of the raw body, keyed on the channel secret |
| `destination` | Bot user ID the events are for (pick the channel secret per bot if you run several) |
| `events[].webhookEventId` | Unique event ID (ULID). Use it to dedupe. |
| `events[].deliveryContext.isRedelivery` | `true` when LINE is redelivering a failed webhook |
| `events[].replyToken` | Token for the reply message endpoint |

## Environment Variables

```bash
LINE_CHANNEL_SECRET=your_channel_secret   # Console → channel → Basic settings → Channel secret

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 line --path /webhooks/line

```

Paste the URL into **Messaging API → Webhook URL**, click **Verify**, and enable **Use webhook**.

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/line-webhooks/references/overview.md) - LINE webhook events, payload structure, redelivery
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/line-webhooks/references/setup.md) - Channel secret, webhook URL, Verify button, redelivery settings
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/line-webhooks/references/verification.md) - Signature algorithm, SDK and manual code, official test vector, common failures
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/line-webhooks/examples/) - Express, Next.js and FastAPI handlers with tests