Webhook Endpoints API — manage event subscriptions

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

Event	Description
`payment.succeeded`	A payment was collected successfully.
`payment.failed`	A payment attempt failed.
`invoice.paid`	An invoice was paid in full.
`subscription.created`	A new subscription was created.
`subscription.canceled`	A subscription was canceled.

Create a webhook endpoint

POST /v1/webhook_endpoints Registers a new webhook endpoint.

Request parameters

string

required

The HTTPS URL to which Borga will send event payloads.

string[]

required

Array of event type strings to subscribe to (e.g. ["payment.succeeded", "invoice.paid"]). Pass ["*"] to subscribe to all events.

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

string

required

Unique endpoint identifier.

string

required

The registered HTTPS URL.

string[]

required

Array of subscribed event types.

boolean

required

Whether the endpoint is currently active.

string

required

Signing secret for verifying delivery payloads. This value is only returned at creation — store it securely.

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

object[]

required

Array of webhook endpoint objects.

Show endpoint fields

string

required

Unique endpoint identifier.

string

required

The registered HTTPS URL.

string[]

required

Subscribed event types.

boolean

required

Whether the endpoint is active.

string

required

ISO 8601 creation timestamp.

{
  "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

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

string

required

Unique endpoint identifier.

string

required

The registered HTTPS URL.

string[]

required

Array of subscribed event types.

boolean

required

Whether the endpoint is active.

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

string

required

The ID of the endpoint to update.

Request parameters

string

Updated HTTPS URL.

string[]

Updated array of event types. Replaces the existing list entirely.

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

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

string

Filter by endpoint ID.

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

object[]

required

Array of delivery objects.

Show delivery fields

string

required

Unique delivery identifier.

string

required

ID of the webhook endpoint this delivery was sent to.

string

required

The event type that triggered the delivery.

string

required

Delivery status. One of delivered or failed.

number

HTTP status code returned by your endpoint.

string

required

ISO 8601 timestamp of the delivery attempt.

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

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.

string

required

Unique identifier for this retry delivery attempt.

string

required

ID of the webhook endpoint.

string

required

The event type that was retried.

string

required

Delivery status of the retry attempt.

number

HTTP status code returned by your endpoint.

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"
}

Overview

Payments

Subscriptions

Billing

Configuration

Webhook Endpoints API — manage event subscriptions

Create a webhook endpoint

Request parameters

Response fields

List webhook endpoints

Response fields

Retrieve a webhook endpoint

Path parameters

Response fields

Update a webhook endpoint

Path parameters

Request parameters

Response fields

Delete a webhook endpoint

Path parameters

Response fields

List webhook deliveries

Query parameters

Response fields

Retry a webhook delivery

Path parameters

Response fields

​Create a webhook endpoint

​Request parameters

​Response fields

​List webhook endpoints

​Response fields

​Retrieve a webhook endpoint

​Path parameters

​Response fields

​Update a webhook endpoint

​Path parameters

​Request parameters

​Response fields

​Delete a webhook endpoint

​Path parameters

​Response fields

​List webhook deliveries

​Query parameters

​Response fields

​Retry a webhook delivery

​Path parameters

​Response fields

Create a webhook endpoint

Request parameters

Response fields

List webhook endpoints

Response fields

Retrieve a webhook endpoint

Path parameters

Response fields

Update a webhook endpoint

Path parameters

Request parameters

Response fields

Delete a webhook endpoint

Path parameters

Response fields

List webhook deliveries

Query parameters

Response fields

Retry a webhook delivery

Path parameters

Response fields