Receive real-time notifications when subscribed API endpoints refresh. Register your HTTPS endpoint through the Universe portal to receive your webhook secret.
When an API endpoint refreshes, we send an HTTP POST to your registered URL with the following specification.
| Property | Value |
|---|---|
| Method | POST |
| Content-Type | application/json |
| Timeout | 30 seconds |
Each request includes these headers for authentication and tracking:
| Header | Required | Description | Example |
|---|---|---|---|
X-Signature | Yes | HMAC-SHA256 signature | sha256=a1b2c3d4e5... |
X-Timestamp | Yes | Unix timestamp (seconds) | 1704067200 |
X-Delivery-ID | Yes | Unique delivery identifier (UUID) | 550e8400-e29b-41d4-... |
X-Event-Type | Yes | Event type | api.data.refreshed |
Content-Type | Yes | Always application/json | application/json |
Authorization | Conditional | Basic Auth (if configured) | Basic dXNlcjpwYXNz |
User-Agent | Yes | Service identifier | MarketCheck |
The request body contains event details in JSON format:
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"event_type": "api.data.refreshed",
"event_data": {
"endpoint": "/search/car/active",
"event_timestamp": "2025-01-15T14:30:00.000Z"
}
}
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Unique identifier (matches X-Delivery-ID) |
event_type | string | Currently api.data.refreshed |
event_data.endpoint | string | API endpoint that was refreshed |
event_data.event_timestamp | string (ISO 8601) | When the refresh occurred |
Your endpoint's response determines how we handle the delivery:
| Response | Behavior |
|---|---|
| 2xx (Success) | Delivery complete, no retry |
| 408, 429 (Timeout/Rate Limit) | Will retry automatically |
| 5xx (Server Error) | Will retry automatically |
| 4xx (Other Client Errors) | Permanently failed, no retry |
| No Response (Timeout) | Will retry automatically |
Recommended success response:
{
"status": "accepted",
"message": "Webhook processed successfully",
"delivery_id": "550e8400-e29b-41d4-a716-446655440000"
}
| Attempt | Delay |
|---|---|
| 1 | Immediate |
| 2 | 1 second |
| 3 (final) | 2 seconds |
After 3 failed attempts, the delivery is marked as permanently failed.
Every webhook request is cryptographically signed. Always verify the signature before processing to ensure the request originated from MarketCheck.
Follow these steps to verify the X-Signature header:
sha256= prefix from X-Signature headersort_keys=True, separators=(',', ':'), ensure_ascii=False{X-Timestamp}.{normalized_json}Reject requests with timestamps older than 5 minutes to prevent replay attacks.
Handle webhooks reliably with these patterns.
Webhooks may be delivered multiple times due to retries or network issues. Each delivery attempt receives a unique X-Delivery-ID, including retries. For event-level deduplication, use event_data.endpoint + event_data.event_timestamp as a composite key.