Registration and Management
Registering Webhooks
API Endpoint
POST /webhooks/
Register a new webhook endpoint to start receiving event notifications.
Request Parameters
Parameter | Type | Required | Description |
|---|---|---|---|
callback_url | string (URL) | Yes | Your publicly accessible HTTPS endpoint that will receive webhook events. Must be unique per company. |
callback_api_key | string | No | Optional API key that Jetpay will include when calling your endpoint for additional authentication. |
max_batch_size | integer | No | Maximum number of events to include in a single webhook delivery. Range: 1-100. Default: 10. |
max_wait_seconds | integer | No | Maximum time (in seconds) to wait before sending a batch if max_batch_size isn't reached. Range: 60-3600. Default: 60. |
replay_from_event_id | integer | No | Replay all events starting from this event ID (inclusive). Useful for recovery or backfilling. |
replay_from_timestamp | string (ISO 8601) | No | Replay all events created at or after this timestamp. Alternative to replay_from_event_id. |
Response Fields
Field | Type | Description |
|---|---|---|
identifier | string (UUID) | Unique identifier for managing this webhook (use in GET/PATCH/DELETE operations) |
callback_url | string | The registered webhook endpoint URL |
state | string | Current webhook state (initially ACTIVE) |
last_sent_event_id | integer | ID of the most recent event successfully delivered (null if none sent yet) |
max_batch_size | integer | Configured maximum batch size |
max_wait_seconds | integer | Configured maximum wait time |
Unique URL Constraint
Each company can only register one webhook per unique URL. Attempting to register a duplicate URL will return a validation error. If you need to update an existing webhook's configuration, use the PATCH endpoint instead.
Example Response
{
"identifier": "550e8400-e29b-41d4-a716-446655440000",
"callback_url": "https://your-domain.com/webhooks/jetpay",
"callback_api_key": "yourAPIkey",
"state": "active",
"last_sent_event_id": null,
"max_batch_size": 10,
"max_wait_seconds": 60,
}Managing Webhooks
You can view our detailed schema for all webhook related API requests here.
List All Webhooks
GET /webhooks/
Retrieve all webhook configurations for your company.
Response: Array of webhook objects with all configuration fields.
Retrieve a Specific Webhook
GET /webhooks/{identifier}/
Retrieve details for a specific webhook using its identifier (UUID).
Path Parameters:
- identifier: The UUID returned when the webhook was created
Response: Single webhook object with all configuration fields.
Update a Webhook
PATCH /webhooks/{identifier}/
Update configuration for an existing webhook.
Path Parameters:
- identifier: The UUID of the webhook to update
Request Body: Include only the fields you want to update:
- callback_url
- callback_api_key
- max_batch_size
- max_wait_seconds
- replay_from_event_id
- replay_from_timestamp
Response: Updated webhook object with all configuration fields.
Note: Updating replay_from_event_id or replay_from_timestamp will trigger replay of historical events starting from that point.
Delete a Webhook
DELETE /webhooks/{identifier}/
Permanently delete a webhook configuration. Event delivery will stop immediately.
Path Parameters:
- identifier: The UUID of the webhook to delete
Response: HTTP 204 No Content on success
Warning: Deletion is permanent. If you need to temporarily stop receiving events, consider using a different approach specific to your integration needs.