API reference
Webhook operations
Inspect deliveries, retry, and replay.
6 endpoints. Every path below is relative to the base URL.
On this page
https://api-uat.softsages.com/coreGET/api/v1/inkfree/webhooks/metrics
Delivery counters per subscription
Requires the X-API-Key header
Returns delivery counts broken down by subscription and status — a quick health check for whether events are landing.
Responses
Counters by subscription.
Returns object
| Field | Type | Required | Description |
|---|---|---|---|
account | string | Optional | — |
app | string | Optional | — |
by_subscription | object | Optional | — |
{
"account": "acme",
"app": "inkfree",
"by_subscription": {
"whk_123": {
"pending": 0,
"delivered": 412,
"failed": 3,
"dead_lettered": 1
}
}
}The API key is missing, malformed, unknown, expired, revoked, or inactive.
Returns Error
{
"code": 401,
"message": "Invalid API key"
}Per-key rate limit exceeded. Back off and retry.
Returns Error
{
"code": 429,
"message": "Rate limit exceeded. Try again later."
}Example request
curl "https://api-uat.softsages.com/core/api/v1/inkfree/webhooks/metrics" \
-H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"POST/api/v1/inkfree/webhooks/{id}/test
Send a test event
Requires the X-API-Key header
Dispatches a synthetic inkfree.test event to the subscription's target URL. This creates a real delivery record and exercises the full signing and delivery path, so it is the reliable way to verify a receiver's signature verification before going live.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Required | Webhook subscription id — a 36-character UUID.Example: whk_123 |
Responses
Test delivery queued.
Returns object
| Field | Type | Required | Description |
|---|---|---|---|
delivery_id | string | Optional | — |
message | string | Optional | — |
{
"delivery_id": "8f14e45f-ea6d-4b1f-9b3a-1c2d3e4f5a6b",
"message": "Test webhook queued."
}The API key is missing, malformed, unknown, expired, revoked, or inactive.
Returns Error
{
"code": 401,
"message": "Invalid API key"
}The subscription does not exist, or it belongs to another tenant. The two cases are deliberately indistinguishable.
Returns Error
{
"code": 404,
"message": "webhook subscription not found"
}Per-key rate limit exceeded. Back off and retry.
Returns Error
{
"code": 429,
"message": "Rate limit exceeded. Try again later."
}Example request
curl -X POST "https://api-uat.softsages.com/core/api/v1/inkfree/webhooks/whk_123/test" \
-H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"GET/api/v1/inkfree/webhooks/{subscriptionId}/deliveries
List delivery history
Requires the X-API-Key header
Returns delivery attempts for a subscription, newest first, capped at 100. Use this to diagnose failures — each row carries the attempt count, the last HTTP response code, and the payload that was sent.
This is also how to retrieve a payload that was truncated in transit: deliveries capped at 256 KiB arrive with X-Inkfree-Truncated: true, and the full body can be read here.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
subscriptionId | path | string | Required | Subscription id.Example: whk_123 |
status | query | string | Optional | Filter by delivery status: pending, delivered, failed, or dead_lettered.pendingdeliveredfaileddead_letteredExample: failed |
Responses
Up to 100 deliveries, newest first.
Returns WebhookDelivery[]
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Optional | Delivery id — a UUID, and the value sent as the X-Inkfree-Delivery header. |
subscriptionId | string | Optional | Subscription this delivery belongs to. |
eventId | string | Optional | Id of the event being delivered. |
eventType | string | Optional | Event type, e.g. envelope.completed, or inkfree.test for test dispatches. |
payload | string | Optional | Raw JSON body sent to the target URL. Read the full payload here when a delivery arrived truncated. |
status | string | Optional | Current state of the delivery.pendingdeliveredfaileddead_lettered |
attempts | integer | Optional | Number of attempts made so far. |
lastResponseCode | integer | Optional | HTTP status returned by the target on the last attempt. |
nextAttemptAt | string | Optional | When the next retry is scheduled, formatted MM/dd/yyyy HH:mm:ss. |
lastAttemptAt | string | Optional | When the last attempt was made, formatted MM/dd/yyyy HH:mm:ss. |
version | string | Optional | Payload schema version. |
The API key is missing, malformed, unknown, expired, revoked, or inactive.
Returns Error
{
"code": 401,
"message": "Invalid API key"
}The subscription does not exist, or it belongs to another tenant. The two cases are deliberately indistinguishable.
Returns Error
{
"code": 404,
"message": "webhook subscription not found"
}Per-key rate limit exceeded. Back off and retry.
Returns Error
{
"code": 429,
"message": "Rate limit exceeded. Try again later."
}Example request
curl "https://api-uat.softsages.com/core/api/v1/inkfree/webhooks/whk_123/deliveries" \
-H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"POST/api/v1/inkfree/deliveries/{deliveryId}/retry
Retry one delivery
Requires the X-API-Key header
Re-sends a single delivery using its original payload, event type, and subscription. Works on delivered, failed, and dead_lettered rows.
A retry creates a new delivery record with a new id rather than mutating the original, so your receiver will see a X-Inkfree-Delivery header it has not seen before. Deduplicate on the event's own identifier if you need to suppress the repeat.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
deliveryId | path | string | Required | Id of the delivery to retry.Example: 8f14e45f-ea6d-4b1f-9b3a-1c2d3e4f5a6b |
Responses
Retry queued.
Returns object
| Field | Type | Required | Description |
|---|---|---|---|
original_delivery_id | string | Optional | — |
new_delivery_id | string | Optional | — |
subscription_id | string | Optional | — |
{
"original_delivery_id": "8f14e45f-ea6d-4b1f-9b3a-1c2d3e4f5a6b",
"new_delivery_id": "b2c3d4e5-f6a7-4890-b1c2-d3e4f5a6b7c8",
"subscription_id": "whk_123"
}The API key is missing, malformed, unknown, expired, revoked, or inactive.
Returns Error
{
"code": 401,
"message": "Invalid API key"
}Delivery not found, or it belongs to another tenant.
Returns Error
{
"code": 404,
"message": "delivery not found"
}Per-key rate limit exceeded. Back off and retry.
Returns Error
{
"code": 429,
"message": "Rate limit exceeded. Try again later."
}Example request
curl -X POST "https://api-uat.softsages.com/core/api/v1/inkfree/deliveries/8f14e45f-ea6d-4b1f-9b3a-1c2d3e4f5a6b/retry" \
-H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"POST/api/v1/inkfree/webhooks/{id}/replay/bulk
Bulk replay deliveries
Requires the X-API-Key header
Replays every delivery for a subscription matching a status and time window — the recovery path after an outage on the receiving end.
Defaults to dead_lettered deliveries from the last 24 hours. since_hours is clamped to the range 1–720, and at most 500 deliveries are replayed per call; run the call repeatedly to work through a larger backlog.
The request body is optional; omitting it applies both defaults.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Required | Webhook subscription id — a 36-character UUID.Example: whk_123 |
Request bodyapplication/json · optional
| Field | Type | Required | Description |
|---|---|---|---|
status | string | Optional | Delivery status to replay.pendingdeliveredfaileddead_lettereddefault: "dead_lettered" |
since_hours | integer | Optional | How many hours back to look. Values outside 1–720 are clamped.default: 24 · range: 1–720 |
{
"status": "dead_lettered",
"since_hours": 48
}Responses
Replay queued.
Returns object
| Field | Type | Required | Description |
|---|---|---|---|
subscription_id | string | Optional | — |
status_filter | string | Optional | — |
since | string (date-time) | Optional | — |
replayed | integer | Optional | Number of deliveries queued, capped at 500. |
{
"subscription_id": "whk_123",
"status_filter": "dead_lettered",
"since": "2026-01-13T10:30:00",
"replayed": 17
}The API key is missing, malformed, unknown, expired, revoked, or inactive.
Returns Error
{
"code": 401,
"message": "Invalid API key"
}The subscription does not exist, or it belongs to another tenant. The two cases are deliberately indistinguishable.
Returns Error
{
"code": 404,
"message": "webhook subscription not found"
}Per-key rate limit exceeded. Back off and retry.
Returns Error
{
"code": 429,
"message": "Rate limit exceeded. Try again later."
}Example request
curl -X POST "https://api-uat.softsages.com/core/api/v1/inkfree/webhooks/whk_123/replay/bulk" \
-H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"status": "dead_lettered",
"since_hours": 48
}'POST/api/v1/inkfree/webhooks/replay
Replay an arbitrary payload
Requires the X-API-Key header
Queues a delivery with a payload you supply, against an existing subscription. Unlike the retry and bulk-replay endpoints, which reuse a stored payload, this one sends exactly the body you pass — useful for reproducing a specific event against a receiver under test.
All three fields are required; each missing one is rejected with its own 400.
Request bodyapplication/json · required
Schema: ReplayRequest
| Field | Type | Required | Description |
|---|---|---|---|
subscriptionId | string | Required | Subscription to deliver to. |
eventType | string | Required | Event type to label the delivery with. |
payload | string | Required | Raw JSON string to deliver as the request body. |
{
"subscriptionId": "whk_123",
"eventType": "envelope.completed",
"payload": "{\"envelope_id\":\"env_xyz789\",\"status\":\"Signed\"}"
}Responses
Replay queued.
Returns ApiResponse
| Field | Type | Required | Description |
|---|---|---|---|
code | integer | Optional | HTTP status code, repeated in the body. |
message | string | Optional | Created object id, or a confirmation message. |
{
"code": 200,
"message": "Webhook replay queued."
}subscriptionId, eventType, or payload is missing.
Returns Error
{
"code": 400,
"message": "subscriptionId is required"
}The API key is missing, malformed, unknown, expired, revoked, or inactive.
Returns Error
{
"code": 401,
"message": "Invalid API key"
}The subscription does not exist, or it belongs to another tenant. The two cases are deliberately indistinguishable.
Returns Error
{
"code": 404,
"message": "webhook subscription not found"
}Per-key rate limit exceeded. Back off and retry.
Returns Error
{
"code": 429,
"message": "Rate limit exceeded. Try again later."
}Example request
curl -X POST "https://api-uat.softsages.com/core/api/v1/inkfree/webhooks/replay" \
-H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"subscriptionId": "whk_123",
"eventType": "envelope.completed",
"payload": "{\"envelope_id\":\"env_xyz789\",\"status\":\"Signed\"}"
}'