Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.borga.is/llms.txt

Use this file to discover all available pages before exploring further.

Webhook endpoints receive HTTP POST notifications from Borga when events occur in your account — for example, when a payment succeeds or a subscription is canceled. Register an endpoint with a list of event types to subscribe to, and Borga will deliver a signed payload to your URL each time a matching event occurs.
Every delivery is signed using your endpoint’s secret. Verify the Borga-Signature header on each incoming request by computing an HMAC-SHA256 of the raw request body using the signing secret. Reject any request that does not match.
Supported events
EventDescription
payment.succeededA payment was collected successfully.
payment.failedA payment attempt failed.
invoice.paidAn invoice was paid in full.
subscription.createdA new subscription was created.
subscription.canceledA subscription was canceled.

​
Create a webhook endpoint

POST /v1/webhook_endpoints Registers a new webhook endpoint.

​
Request parameters

​
url
string
required
The HTTPS URL to which Borga will send event payloads.
​
events
string[]
required
Array of event type strings to subscribe to (e.g. ["payment.succeeded", "invoice.paid"]). Pass ["*"] to subscribe to all events.
​
enabled
boolean
Whether the endpoint should receive deliveries. Defaults to true.
curl --request POST \
  --url https://api.borga.is/v1/webhook_endpoints \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://your-server.example.com/webhooks/borga",
    "events": [
      "payment.succeeded",
      "payment.failed",
      "invoice.paid",
      "subscription.created",
      "subscription.canceled"
    ]
  }'

​
Response fields

​
id
string
required
Unique endpoint identifier.
​
url
string
required
The registered HTTPS URL.
​
events
string[]
required
Array of subscribed event types.
​
enabled
boolean
required
Whether the endpoint is currently active.
​
secret
string
required
Signing secret for verifying delivery payloads. This value is only returned at creation — store it securely.
​
created_at
string
required
ISO 8601 timestamp of when the endpoint was created.
{
  "id": "we_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "url": "https://your-server.example.com/webhooks/borga",
  "events": [
    "payment.succeeded",
    "payment.failed",
    "invoice.paid",
    "subscription.created",
    "subscription.canceled"
  ],
  "enabled": true,
  "secret": "whsec_...",
  "created_at": "2026-04-29T10:15:00Z"
}

​
List webhook endpoints

GET /v1/webhook_endpoints Returns a list of all registered webhook endpoints. 
curl --request GET \
  --url https://api.borga.is/v1/webhook_endpoints \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx"

​
Response fields

​
data
object[]
required
Array of webhook endpoint objects.
{
  "data": [
    {
      "id": "we_01hx9z3k2mfq7nbvd4cw8ej5rt",
      "url": "https://your-server.example.com/webhooks/borga",
      "events": ["payment.succeeded", "invoice.paid"],
      "enabled": true,
      "created_at": "2026-04-29T10:15:00Z"
    }
  ]
}

​
Retrieve a webhook endpoint

GET /v1/webhook_endpoints/{id} Retrieves an existing webhook endpoint. The secret is not returned after initial creation.

​
Path parameters

​
id
string
required
The ID of the endpoint to retrieve.
curl --request GET \
  --url https://api.borga.is/v1/webhook_endpoints/we_01hx9z3k2mfq7nbvd4cw8ej5rt \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx"

​
Response fields

​
id
string
required
Unique endpoint identifier.
​
url
string
required
The registered HTTPS URL.
​
events
string[]
required
Array of subscribed event types.
​
enabled
boolean
required
Whether the endpoint is active.
​
created_at
string
required
ISO 8601 timestamp of when the endpoint was created.
{
  "id": "we_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "url": "https://your-server.example.com/webhooks/borga",
  "events": ["payment.succeeded", "invoice.paid"],
  "enabled": true,
  "created_at": "2026-04-29T10:15:00Z"
}

​
Update a webhook endpoint

PATCH /v1/webhook_endpoints/{id} Updates an existing webhook endpoint. Only the fields you provide are changed.

​
Path parameters

​
id
string
required
The ID of the endpoint to update.

​
Request parameters

​
url
string
Updated HTTPS URL.
​
events
string[]
Updated array of event types. Replaces the existing list entirely.
​
enabled
boolean
Set to false to pause deliveries to this endpoint.
curl --request PATCH \
  --url https://api.borga.is/v1/webhook_endpoints/we_01hx9z3k2mfq7nbvd4cw8ej5rt \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "enabled": false
  }'

​
Response fields

Returns the updated endpoint object. See retrieve a webhook endpoint for the full field reference. 
{
  "id": "we_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "url": "https://your-server.example.com/webhooks/borga",
  "events": ["payment.succeeded", "invoice.paid"],
  "enabled": false,
  "created_at": "2026-04-29T10:15:00Z"
}

​
Delete a webhook endpoint

DELETE /v1/webhook_endpoints/{id} Permanently deletes a webhook endpoint. Borga will stop delivering events to this URL immediately.

​
Path parameters

​
id
string
required
The ID of the endpoint to delete.
curl --request DELETE \
  --url https://api.borga.is/v1/webhook_endpoints/we_01hx9z3k2mfq7nbvd4cw8ej5rt \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx"

​
Response fields

Returns an empty body with a 204 No Content status on success. 
{}

​
List webhook deliveries

GET /v1/webhook_deliveries Returns a paginated list of delivery attempts for a webhook endpoint, ordered by creation date descending. Use this to audit which events were received and identify failures.

​
Query parameters

​
endpoint
string
Filter by endpoint ID.
​
limit
number
Maximum number of deliveries to return per page.
curl --request GET \
  --url "https://api.borga.is/v1/webhook_deliveries?endpoint=we_01hx9z3k2mfq7nbvd4cw8ej5rt&limit=20" \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx"

​
Response fields

​
data
object[]
required
Array of delivery objects.
​
has_more
boolean
required
Whether more deliveries exist beyond this page.
{
  "data": [
    {
      "id": "wd_01hx9z3k2mfq7nbvd4cw8ej5rt",
      "endpoint": "we_01hx9z3k2mfq7nbvd4cw8ej5rt",
      "event_type": "payment.succeeded",
      "status": "delivered",
      "response_code": 200,
      "created_at": "2026-04-29T10:15:05Z"
    }
  ],
  "has_more": false
}

​
Retry a webhook delivery

POST /v1/webhook_deliveries/{id}/retry Retries a previously failed delivery. Borga re-sends the original event payload to the registered endpoint URL.

​
Path parameters

​
id
string
required
The ID of the delivery to retry.
curl --request POST \
  --url https://api.borga.is/v1/webhook_deliveries/wd_01hx9z3k2mfq7nbvd4cw8ej5rt/retry \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx"

​
Response fields

Returns the new delivery attempt object.
​
id
string
required
Unique identifier for this retry delivery attempt.
​
endpoint
string
required
ID of the webhook endpoint.
​
event_type
string
required
The event type that was retried.
​
status
string
required
Delivery status of the retry attempt.
​
response_code
number
HTTP status code returned by your endpoint.
​
created_at
string
required
ISO 8601 timestamp of the retry attempt.
{
  "id": "wd_01hx9z3k2mfq7nbvd4cw8ej5rt2",
  "endpoint": "we_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "event_type": "payment.succeeded",
  "status": "delivered",
  "response_code": 200,
  "created_at": "2026-04-29T11:00:00Z"
}