---
title: "Batch events"
method: POST
path: "batchEvent"
tags: ["Webhooks"]
---

# Batch events

`POST batchEvent` (webhook)

Sent once per batch when it reaches its final status, usually within a minute, to each enabled webhook that lists the event.
The events are batch.completed, batch.failed, batch.expired (the 24 hour completion window ended first) and batch.cancelled. A batch that reached its final status more than 24 hours before it is picked up sends none. Listing a batch event needs batch read access.

## Headers

- `X-OpenRelay-Signature` string, required
- `X-OpenRelay-Event` string, required
- `X-OpenRelay-Delivery` string, uuid, required
- `User-Agent` 'OpenRelay-Webhook/1.0', required
- `X-VectorLay-Signature` string, required
- `X-VectorLay-Event` string, required
- `X-VectorLay-Delivery` string, uuid, required

## Payload

- BatchWebhookEvent: The body of a batch.completed, batch.failed, batch.expired or batch.cancelled delivery: the batch's final state.
  - `created_at` string, date-time, required: When the batch reached its final status, RFC 3339 in UTC to the second.
  - `data` object, required
    - `batch_id` string, required: The batch's id (batch_…).
    - `cost_nano_usd` integer, required: What the batch cost, in billionths of a dollar: the batch object's usage.cost_nano_usd, 0 when it used nothing. A failed batch's failure code and message are not included; read them from the batch.
    - `error_file_id` string, nullable, required: The file holding the requests that failed; null when it has none.
    - `output_file_id` string, nullable, required: The file holding the batch's responses; null when it has none.
    - `request_counts` BatchRequestCounts, required: Request counters. A create sets total and failed (the records it rejected); completed and failed then grow as records finish.
      - `completed` integer, required: Records that finished with a response.
      - `failed` integer, required: Records rejected at create plus records that failed while the batch ran.
      - `total` integer, required: Records in the input, rejected ones included. Blank lines are not records.
    - `status` 'completed' | 'failed' | 'expired' | 'cancelled', required: The batch's final status, the one the event names.
  - `id` string, required: The event's id, evt_ followed by a UUID derived from the event type and the batch id, so a batch's event always has the same id.
  - `type` 'batch.completed' | 'batch.failed' | 'batch.expired' | 'batch.cancelled', required

## Acknowledgement `2XX`

Delivered. Any 2xx status within 10 seconds counts, and its body is not kept.

## Other responses

- `default`: Any other final status, a connection error, or no answer within 10 seconds fails the attempt, and up to the first 1000 bytes of the response body are kept in the delivery's error message. Redirects are followed, at most 9 (10 requests in all), each hop held to the webhook URL's rules (https, no credentials, no internal address), and the last status counts. A failed delivery is tried at most 3 times: the second attempt about 10 seconds after the first and the third about 60 seconds after the second, each run by a scheduler that checks every 30 seconds, so a retry can come up to 30 seconds later. A retry that comes due while the webhook is disabled or deleted is dropped.

---

[API](https://skmtc.dev/openrelay/apis/openrelay-api.md) - [All operations](https://skmtc.dev/openrelay/apis/openrelay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/openrelay/apis/openrelay-api/revisions/7fe59d94a9f5?raw)