Configuration
Jetpay webhooks offer flexible configuration to optimize delivery based on your needs.
Batch Size (max_batch_size)
Range: 1-100 events per delivery Default: 10 events
Controls the maximum number of events included in a single webhook request. Higher batch sizes reduce the number of HTTP requests but increase payload size and processing time per request.
Considerations:
- Small batches (1-10): Lower latency, more real-time, more HTTP requests
- Medium batches (10-50): Balanced approach, good for most use cases
- Large batches (50-100): Fewer requests, higher throughput, delayed delivery for low-volume events
Wait Time (max_wait_seconds)
Range: 60-3600 seconds (1 minute to 1 hour) Default: 60 seconds
Specifies the maximum time to wait before sending a batch if max_batch_size hasn't been reached. This prevents events from being held indefinitely during low-activity periods.
Considerations:
- Short wait (60-300s): More real-time delivery, may send smaller batches
- Medium wait (300-900s): Balanced approach
- Long wait (900-3600s): Maximizes batch fullness, accepts higher latency
How Batching Works
Webhook delivery is triggered when either condition is met:
- Batch Size Reached: Accumulated undelivered events reach max_batch_size
- Wait Time Elapsed: max_wait_seconds have passed since the oldest undelivered event
This ensures both throughput efficiency and acceptable latency.
Example Scenarios:
- High-volume period: Events accumulate quickly, batches sent when max_batch_size is reached (e.g., every few seconds)
- Low-volume period: Few events occur, batches sent after max_wait_seconds elapses (e.g., every 60 seconds with 2-3 events)
- No events: No webhook requests are sent (no empty batches)
Replay from Event ID or Timestamp
Two options for replaying historical events:
replay_from_event_id
Start delivery from a specific event ID (inclusive). All events with ID >= this value will be delivered.
Use Cases:
- Recovering from a known missed event
- Reprocessing events after fixing a bug in your handler
- Backfilling a new integration
replay_from_timestamp
Start delivery from a specific ISO 8601 timestamp (inclusive). All events created at or after this time will be delivered.
Use Cases:
- Time-based recovery ("replay everything since yesterday")
- Initial backfill for new webhooks
- Reprocessing after downtime
Important Notes:
- Replay is sequential and respects batch size and wait time settings
- Large replays may take time to complete (events delivered in batches)
- Only one replay parameter should be specified (ID takes precedence if both provided)
- Setting replay parameters via PATCH will restart event delivery from that point