A Batch completed webhook fires once per batch, after every item has finished. The payload has the same shape as GET /batches/:id and includes the per-item results so you can see exactly which items failed and why.
For the general mechanics of how webhooks behave (URL, places, custom headers, API version, retries, idempotence, disabling), see Webhooks. This article only covers the Trigger on options that are specific to batch completions, and how to handle failed items.
Adding a Batch completed webhook
Manual Integration: Settings → Integrations → Webhooks → Add.
Partner Integration: Developer → Webhooks → Add.
Pick Batch completed as the webhook type. The wizard then shows a Trigger on step with the batch-specific filter described below.
Trigger on
Which batches to trigger on
The Which batches to trigger on setting (onlyOnItemFailures in the API) controls whether you receive every completed batch or only ones with failures:
Trigger for every completed batch — fires for every batch, whether items succeeded or failed.
Only trigger for batches with failed items — fires only when at least one item failed.
Handling failed items
If you're using an access key batch action, an item failure means access has not been granted to that user and Parakey has no way to tell them. Only your integration knows who triggered the action and who was affected, so we strongly recommend that every integration listens for failed items at minimum — use Only trigger for batches with failed items, or listen to every completed batch if you also want the success cases.
When a failed batch arrives, surface it to the people involved, for example by:
Notifying whoever triggered the action with what to do next (fix the email, re-issue the key, etc.) — email, push, or in-app message.
Flagging the affected end users in your system (e.g. a "key not delivered" badge or an "access not granted" report) so the failure isn't lost after any one-off notification.