← All posts
Tutorial

LINE Webhook Multiple Events: Handle Partial Batch Failures

A LINE Messaging API webhook can contain multiple events, including events from different users. Do not process only events[0], assign the whole request to its first sender, or return success after saving only part of it. Authenticate the request, durably accept every event, then return 200. Deduplicate individual events by webhookEventId so repeated delivery does not repeat business work.

Key takeaways

  • One HTTP request is not necessarily one event, user, or conversation.
  • Acknowledgement covers the request; your storage and processing records need event-level granularity.
  • deliveryContext.isRedelivery is diagnostic context, not a duplicate-detection key.
  • LINE redelivery is a recovery aid, not a guaranteed archive or an application worker retry mechanism.

Why processing the first event loses work

LINE’s development guidelines explicitly describe a message from person A and a follow event from person B appearing in the same webhook. The Messaging API reference defines the request’s events array and the event objects within it.

That creates two independent boundaries:

BoundaryWhat it representsIncorrect shortcut
HTTP requestThe authenticated delivery being acknowledgedTreat the first successful event as success for everything
Event objectOne event with its own type, source, and IDCopy the first event’s sender or message fields to its neighbors

Route each event by its own type and source. A follow event is not a message with missing text. The top-level destination identifies the receiving bot, not a customer to whom all events belong.

An empty array is a separate valid verification case. Use the empty-events verification guide for that path; this article addresses a non-empty batch whose acceptance can fail partway through.

Make durable batch acceptance the acknowledgement gate

First verify x-line-signature over the untouched request body using the channel secret, following LINE’s signature guide. Parse only after verification. Bind the request to the channel configuration whose secret was used; do not select a customer or tenant from the first event.

A recommended implementation is a database-backed inbox:

  1. Validate the outer structure and every event’s required intake identifiers.
  2. In one database transaction, insert each event with a unique key combining your channel scope and webhookEventId.
  3. Treat an existing key as already accepted. Do not overwrite its processing state with a fresh pending state.
  4. Commit before returning 200. Workers discover committed inbox rows and perform slow work independently.

The following JavaScript sketches that boundary. inbox.transaction and tx.insertIfAbsent are application abstractions, not LINE methods or an SDK. Implement them with a real transaction and unique constraint. channelKey comes from trusted receiver configuration; the input has already passed signature verification.

async function acceptVerifiedLineBatch(payload, channelKey, inbox) {
  if (!payload || !Array.isArray(payload.events)) {
    throw new Error('Invalid events array');
  }
  for (const event of payload.events) {
    if (!event || typeof event.webhookEventId !== 'string' ||
        event.webhookEventId.length === 0 ||
        typeof event.type !== 'string') {
      throw new Error('Invalid event envelope');
    }
  }

  await inbox.transaction(async (tx) => {
    for (const event of payload.events) {
      await tx.insertIfAbsent(channelKey, event.webhookEventId, event);
    }
  });
  return 200;
}

This is not a complete HTTP server. The caller must reject invalid signatures, handle parsing failures, and avoid sending success if validation or commit fails. For a temporary storage outage, a non-2xx response such as 503 is an application choice, not a promise that LINE will recover every event.

Avoid inserting an inbox row and separately publishing to a queue without a recovery mechanism. A crash between those writes can leave accepted work undiscoverable. Let workers read the durable inbox, or use a transactional outbox for dispatch.

Recover from partial failure without depending on batch identity

LINE’s receiving guide says duplicate events can occur, and recommends webhookEventId for detection. Redelivery preserves the event ID while changing deliveryContext.isRedelivery. Do not depend on the same events arriving together again or hash the complete HTTP body as the business deduplication key.

For an illustrative batch containing A and B:

Failure pointRecommended outcome
Transaction fails while saving BRoll back new inserts; do not acknowledge successful intake
A was already stored by an earlier requestKeep A’s existing record; still accept B
Commit succeeds but the HTTP response is lostRepeated event IDs find existing rows rather than new jobs
Worker fails after HTTP successRetry from your inbox, not by waiting for another LINE delivery
Valid but unhandled event type arrivesPersist it for controlled review; do not silently discard its neighbors

If an existing implementation commits events individually, retain those records and deduplicate them on any repeated delivery. Never mark the entire request completed merely because its first insert succeeded.

Worker retries need separate safeguards. A CRM operation or reply may succeed before the worker records completion. Preserve uncertain outcomes and use the downstream system’s documented idempotency support where available. For replies, the reply-token recovery guide explains why a repeated event is not a fresh independent sending opportunity.

Keep redelivery limits and UnifyPort contracts separate

LINE redelivery requires the feature to be enabled and a failed webhook response. LINE does not disclose the retry count or interval and explicitly does not guarantee reliable delivery through redelivery. It also warns that event arrival order can differ from occurrence order. Keep event timestamp values for context; batch position is not a global sequence.

UnifyPort’s unofficial interface is a separate connected-account path. Its standard envelope uses id, type, provider, account_id, occurred_at, and data, not LINE’s native events array. Its delivery contract uses X-Device-Signature with a configured signing_secret, and acknowledges any 2xx response.

Share the durable-inbox design, not the parser or signature string. Do not wrap a missing native events field as an empty verification request. Keep the official Messaging API when the required identity is the LINE Official Account; changing integrations is not a recovery mechanism for a partially accepted request.

FAQ

Can I return success when one event fails?

Only if every event has already been durably accepted and the failure is downstream processing that your system can recover. If some events were never stored, do not report successful intake for the request.

Should I discard every event marked isRedelivery?

No. It may be your first successfully received copy. Consult the event’s durable deduplication record instead.

Does Promise.all make batch handling safe?

No. Concurrent operations can partially succeed. Safety comes from durable acceptance, unique event keys, and recovery semantics—not the JavaScript scheduling primitive.

Next step and sources

Test a mixed-user batch, an existing event beside a new event, failed commit, lost acknowledgement, and a worker crash. These are proposed tests, not reported results. For a separate UnifyPort receiver, start with the webhook delivery reference.

Official sources checked on 2026-11-13:

UnifyPort API

Turn messaging integration into a stable product pipeline.

Start by sending through one API, then bring every inbound message back into your business system with standard events.