Webhooks
Check API availability and confirm access in your target environment before integrating.
| Operation | Method and route | Availability |
|---|---|---|
| Create an endpoint | POST /v1/webhook-endpoints | Availability pending |
| List endpoints | GET /v1/webhook-endpoints | Availability pending |
| Update an endpoint | PATCH /v1/webhook-endpoints/{id} | Availability pending |
| Delete an endpoint | DELETE /v1/webhook-endpoints/{id} | Availability pending |
Endpoint management and merchant webhook delivery remain pending availability. Use server-side Checkout retrieval/polling for payment confirmation; see availability. Enable delivery only after confirming your account and environment support these operations.
This reference defines the shared notification endpoints, event format, signature verification, and delivery rules for Checkouts and Refunds. Endpoint management uses the request/authentication, idempotency, pagination, and error conventions in Common conventions. See the receiving guide for application architecture and a downloadable verifier.
Webhook Endpoints
A webhook endpoint is the merchant's server URL for receiving Checkout and Refund notifications. Merchants can configure multiple endpoints, managed separately in each environment. Endpoint counts are subject to the merchant's quota.
The same event is delivered to every enabled endpoint with the same event id. Each endpoint has its own signing secret, enable/disable state, and retry schedule. Failure at one endpoint does not affect another.
Webhook Endpoint Object
Attributes
| Attribute | Type | Description |
|---|---|---|
id | string | Unique endpoint identifier |
url | string | Publicly reachable receiver URL; HTTPS is required in the live environment; HTTP is also allowed in the test environment |
enabled | boolean | Whether delivery is enabled; defaults to true |
secret | string | Signature verification secret; returned only on creation and a valid idempotent retry of that operation; omitted from list and update responses |
created_at | string | Creation time |
updated_at | string | Last update time |
The secret is independent of the API key and must stay on the merchant server.
Object example
Creation returns the signing secret:
{
"id": "we_example",
"url": "https://merchant.example.com/webhooks/invisi",
"enabled": true,
"secret": "whsec_...",
"created_at": "2026-10-15T08:00:00Z",
"updated_at": "2026-10-15T08:00:00Z"
}
Create an endpoint
POST /v1/webhook-endpoints
Creates a Checkout/Refund notification endpoint and generates its signing secret.
Attributes
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | Unique key for this operation; reuse the original value when retrying |
url | body | string | Yes | Publicly reachable receiver URL; live requires HTTPS; test also permits HTTP |
enabled | body | boolean | No | Whether delivery is enabled; defaults to true |
Request example
POST /v1/webhook-endpoints
Authorization: Bearer inv_test_...
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
{
"url": "https://merchant.example.com/webhooks/invisi",
"enabled": true
}
Response example
200 OK, with the complete Webhook Endpoint object including the signing secret. Save secret; subsequent list and update responses omit it.
{
"id": "we_example",
"url": "https://merchant.example.com/webhooks/invisi",
"enabled": true,
"secret": "whsec_...",
"created_at": "2026-10-15T08:00:00Z",
"updated_at": "2026-10-15T08:00:00Z"
}
List endpoints
GET /v1/webhook-endpoints
Returns a paginated list of the current merchant's enabled and disabled endpoints.
Attributes
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
page_size | query | integer | No | Page size; defaults to 20; range 1–100 |
page_token | query | string | No | next_page_token from the previous page; omit for the first page |
Request example
GET /v1/webhook-endpoints?page_size=20
Authorization: Bearer inv_test_...
Response example
200 OK. data is an array of Webhook Endpoint objects without secret. An empty next_page_token means there is no next page.
{
"data": [
{
"id": "we_example",
"url": "https://merchant.example.com/webhooks/invisi",
"enabled": true,
"created_at": "2026-10-15T08:00:00Z",
"updated_at": "2026-10-15T08:00:00Z"
}
],
"next_page_token": ""
}
If no endpoints are configured, the response is {"data":[],"next_page_token":""}.
Update an endpoint
PATCH /v1/webhook-endpoints/{id}
Updates the receiver URL or enable state. Omitted fields retain their values. The signing secret does not change.
Attributes
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | Unique key for this operation; reuse the original value when retrying |
id | path | string | Yes | Unique endpoint identifier |
url | body | string | No | New receiver URL; cannot be cleared; same requirements as creation |
enabled | body | boolean | No | Whether delivery is enabled; false disables delivery |
Request example
PATCH /v1/webhook-endpoints/we_example
Authorization: Bearer inv_test_...
Content-Type: application/json
Idempotency-Key: 65ded8e0-a034-49cb-8d7c-4b279a7382fd
{
"enabled": false
}
Response example
200 OK, with the updated Webhook Endpoint object, without secret.
{
"id": "we_example",
"url": "https://merchant.example.com/webhooks/invisi",
"enabled": false,
"created_at": "2026-10-15T08:00:00Z",
"updated_at": "2026-10-15T08:10:00Z"
}
Delete an endpoint
DELETE /v1/webhook-endpoints/{id}
Deletes an endpoint and stops delivery of new events to it. Recreating an endpoint generates a new ID and signing secret.
Attributes
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | Unique key for this operation; reuse the original value when retrying |
id | path | string | Yes | Unique endpoint identifier |
There is no request body.
Request example
DELETE /v1/webhook-endpoints/we_example
Authorization: Bearer inv_test_...
Idempotency-Key: de68649e-3869-4d8c-b267-61e6e0732311
Response example
200 OK, with the deleted endpoint's ID and deletion result.
{
"id": "we_example",
"deleted": true
}
A valid idempotent retry of the same deletion returns the original successful response.
Error codes
These errors apply to endpoint management. See Error responses for the response structure and common errors.
error.code | HTTP status | Meaning | Operations |
|---|---|---|---|
webhook_endpoint_not_found | 404 | Endpoint does not exist or is inaccessible | Update, delete |
webhook_endpoint_invalid_url | 400 | Receiver URL does not satisfy requirements | Create, update |
webhook_endpoint_limit_exceeded | 409 | Merchant endpoint quota reached | Create |
Webhook Events
The platform sends lightweight notifications (Thin Events) to endpoint URLs over HTTP POST. Events describe a Checkout or Refund change and identify the related resource; retrieve the resource based on related_object.type.
Event Object
Attributes
| Attribute | Type | Description |
|---|---|---|
id | string | Unique event identifier; use to detect duplicate notifications |
type | string | Event type, such as checkout.succeeded for successful Checkout |
related_object | object | Resource related to the event |
related_object.id | string | Resource ID used to retrieve that resource |
related_object.type | string | Resource type: checkout or refund |
created_at | string | Time the event occurred |
Repeated deliveries retain the event ID and content. Retrieving the resource returns its current state, which can include later changes.
Object example
{
"id": "evt_example",
"type": "checkout.succeeded",
"related_object": {
"id": "checkout_example",
"type": "checkout"
},
"created_at": "2026-10-15T08:01:00Z"
}
Related resources
First distinguish the resource by related_object.type, then retrieve its current state with related_object.id:
related_object.type | Retrieval endpoint | Event types |
|---|---|---|
checkout | Retrieve Checkout: GET /v1/checkouts/{id} | checkout.* |
refund | Retrieve Refund: GET /v1/refunds/{id} | Refund events below |
Notifications can arrive more than once or out of order. Deduplicate by event id and retrieve the resource to prevent an earlier notification from overwriting newer state. Refund delivery uses the same event/signature/retry contract. The Refund contract defines these event types:
type | Trigger |
|---|---|
refund.requires_action | Refund created, or execution failure returns it to requires_action, awaiting merchant action |
refund.processing | Refund enters processing, while its result is being verified |
refund.succeeded | Refund enters succeeded, meeting final confirmation requirements |
refund.canceled | Refund enters canceled after successful cancellation |
Repeated verification of the same state does not create another event; re-entering that state creates a new event. Retrieve last_execution_error for execution failure details. checkout.succeeded below illustrates the event format; see the Checkout event types for supported Checkout notifications. Refund operations and event delivery remain subject to availability.
Receive an event
POST {endpoint url}
Attributes
| Location | Attribute | Type | Description |
|---|---|---|---|
| header | Content-Type | string | application/json |
| header | Invisi-Signature | string | Notification signature; see Signature verification |
| body | — | object | Event Object |
Request example
POST /webhooks/invisi HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
Invisi-Signature: t=<unix_seconds>,v1=<signature>
{
"id": "evt_example",
"type": "checkout.succeeded",
"related_object": {
"id": "checkout_example",
"type": "checkout"
},
"created_at": "2026-10-15T08:01:00Z"
}
Response
After verifying the signature and durably saving the event, return 2xx promptly, without a response body. Resource retrieval and fulfillment can run asynchronously. Return 2xx for already accepted duplicates as well, without repeating business actions.
HTTP/1.1 200 OK
Content-Length: 0
2xx acknowledges receipt only. If subsequent business processing fails, the merchant must retry its own work. Events not successfully received follow the delivery rules.
Signature verification
Verify each request with that endpoint's secret before accepting the event. The signature is in the header:
Invisi-Signature: t=<unix_seconds>,v1=<signature>
| Component | Description |
|---|---|
t | Unix timestamp of this delivery, in seconds |
v1 | HMAC-SHA256 signature in lowercase hexadecimal |
-
Read the original request body bytes, preserving spaces, newlines, and field order. Do not parse and reserialize the body before verification.
-
Concatenate the decimal timestamp, a literal period
., and the raw body:signed_payload = t + "." + raw_bodyexpected = hex(HMAC-SHA256(secret, signed_payload)) -
Compare
expectedwithv1using a constant-time comparison. Use the entiresecretreturned on endpoint creation; do not remove a prefix or decode it. -
Check the difference between
tand the current time. Accepting only requests within five minutes in either direction is recommended; keep the server clock synchronized.
Reject the request without processing the event if the signature is absent, malformed, mismatched, or outside the allowed time window.
Every retry has a new delivery timestamp and signature; the event ID and request body stay the same. Timestamp checks do not replace event deduplication.
Delivery and retry
Each delivery has a five-second request timeout. Delivery results are evaluated separately for each endpoint:
| Delivery result | Handling |
|---|---|
2xx response | Successful receipt; stops automatic retry of this event to this endpoint |
Connection failure, response timeout, or non-2xx | Failed receipt; schedules retry |
3xx response | Redirect is not followed; treated as failed receipt |
After a failure, automatic retries use increasing intervals for up to three days after the first delivery. Automatic delivery stops after successful receipt, expiry of the retry period, endpoint disablement, or endpoint deletion. Requests already in flight can still arrive.
Delivery failure does not change Checkout or Refund state. After service recovery, reconcile missing results through GET /v1/checkouts/{id}, GET /v1/checkouts, Retrieve Refund, or List Refunds. Confirm the corresponding route's availability before using it.