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.isRedeliveryis 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:
| Boundary | What it represents | Incorrect shortcut |
|---|---|---|
| HTTP request | The authenticated delivery being acknowledged | Treat the first successful event as success for everything |
| Event object | One event with its own type, source, and ID | Copy 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:
- Validate the outer structure and every event’s required intake identifiers.
- In one database transaction, insert each event with a unique key combining your channel scope and
webhookEventId. - Treat an existing key as already accepted. Do not overwrite its processing state with a fresh pending state.
- 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 point | Recommended outcome |
|---|---|
| Transaction fails while saving B | Roll back new inserts; do not acknowledge successful intake |
| A was already stored by an earlier request | Keep A’s existing record; still accept B |
| Commit succeeds but the HTTP response is lost | Repeated event IDs find existing rows rather than new jobs |
| Worker fails after HTTP success | Retry from your inbox, not by waiting for another LINE delivery |
| Valid but unhandled event type arrives | Persist 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:
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.