Skip to main content

Webhooks

Check API availability and confirm access in your target environment before integrating.

OperationMethod and routeAvailability
Create an endpointPOST /v1/webhook-endpointsAvailability pending
List endpointsGET /v1/webhook-endpointsAvailability pending
Update an endpointPATCH /v1/webhook-endpoints/{id}Availability pending
Delete an endpointDELETE /v1/webhook-endpoints/{id}Availability pending
Pending availability

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​

AttributeTypeDescription
idstringUnique endpoint identifier
urlstringPublicly reachable receiver URL; HTTPS is required in the live environment; HTTP is also allowed in the test environment
enabledbooleanWhether delivery is enabled; defaults to true
secretstringSignature verification secret; returned only on creation and a valid idempotent retry of that operation; omitted from list and update responses
created_atstringCreation time
updated_atstringLast 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​

AttributeLocationTypeRequiredDescription
Idempotency-KeyheaderstringYesUnique key for this operation; reuse the original value when retrying
urlbodystringYesPublicly reachable receiver URL; live requires HTTPS; test also permits HTTP
enabledbodybooleanNoWhether 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​

AttributeLocationTypeRequiredDescription
page_sizequeryintegerNoPage size; defaults to 20; range 1–100
page_tokenquerystringNonext_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​

AttributeLocationTypeRequiredDescription
Idempotency-KeyheaderstringYesUnique key for this operation; reuse the original value when retrying
idpathstringYesUnique endpoint identifier
urlbodystringNoNew receiver URL; cannot be cleared; same requirements as creation
enabledbodybooleanNoWhether 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​

AttributeLocationTypeRequiredDescription
Idempotency-KeyheaderstringYesUnique key for this operation; reuse the original value when retrying
idpathstringYesUnique 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.codeHTTP statusMeaningOperations
webhook_endpoint_not_found404Endpoint does not exist or is inaccessibleUpdate, delete
webhook_endpoint_invalid_url400Receiver URL does not satisfy requirementsCreate, update
webhook_endpoint_limit_exceeded409Merchant endpoint quota reachedCreate

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​

AttributeTypeDescription
idstringUnique event identifier; use to detect duplicate notifications
typestringEvent type, such as checkout.succeeded for successful Checkout
related_objectobjectResource related to the event
related_object.idstringResource ID used to retrieve that resource
related_object.typestringResource type: checkout or refund
created_atstringTime 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"
}

First distinguish the resource by related_object.type, then retrieve its current state with related_object.id:

related_object.typeRetrieval endpointEvent types
checkoutRetrieve Checkout: GET /v1/checkouts/{id}checkout.*
refundRetrieve 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:

typeTrigger
refund.requires_actionRefund created, or execution failure returns it to requires_action, awaiting merchant action
refund.processingRefund enters processing, while its result is being verified
refund.succeededRefund enters succeeded, meeting final confirmation requirements
refund.canceledRefund 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​

LocationAttributeTypeDescription
headerContent-Typestringapplication/json
headerInvisi-SignaturestringNotification signature; see Signature verification
body—objectEvent 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>
ComponentDescription
tUnix timestamp of this delivery, in seconds
v1HMAC-SHA256 signature in lowercase hexadecimal
  1. Read the original request body bytes, preserving spaces, newlines, and field order. Do not parse and reserialize the body before verification.

  2. Concatenate the decimal timestamp, a literal period ., and the raw body:

    signed_payload = t + "." + raw_body
    expected = hex(HMAC-SHA256(secret, signed_payload))
  3. Compare expected with v1 using a constant-time comparison. Use the entire secret returned on endpoint creation; do not remove a prefix or decode it.

  4. Check the difference between t and 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 resultHandling
2xx responseSuccessful receipt; stops automatic retry of this event to this endpoint
Connection failure, response timeout, or non-2xxFailed receipt; schedules retry
3xx responseRedirect 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.