---
title: Registration and Management
slug: registration-and-management
docTags: 
createdAt: 2026-01-22T19:28:50.435Z
---

## 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

:::hint{type="warning"}
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

```json
{
  "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](https://extapi.jetpay.baselinepayments.com/docs#tag/Webhooks-\(v0\)).

### 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.

:::hint{type="info"}
**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.