gobtc payDocs

Webhooks

Configure outbound webhook endpoints (URL, scope, signing secret) so your backend is notified when a payment's status changes, an alternative to polling Get payment.

Create webhook

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/webhook/create

Registers a webhook endpoint. Provide the destination url and a scope (merchant for the whole account, or store / pos to narrow delivery); events defaults to all event types. The response includes the signingSecret shown only once, store it to verify the X-GoBTCPay-Signature header on incoming deliveries.

Authorization: merchantAuth

Body required

application/json
urlstringrequired

Destination URL that receives webhook deliveries.

Example:string
scopeobjectrequired

Which payments this endpoint receives: merchant (whole account), or store / pos to narrow delivery to one store or terminal.

eventsenum[]

Event types this endpoint is subscribed to.

labelstring

Human-readable label for the POS terminal (optional).

Example:Front desk

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /merchant/webhook/create
cURL
curl -X POST "$BASE_URL/merchant/webhook/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "url": "string",
  "scope": {
    "type": "merchant"
  },
  "events": [
    "payment.status.updated"
  ],
  "label": "Front desk"
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "webhook": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "url": "string",
        "scope": {
          "type": "merchant"
        },
        "events": [
          "payment.status.updated"
        ],
        "status": "active",
        "label": "Front desk",
        "createdAt": 1718012345,
        "updatedAt": 1718012345,
        "signingSecret": "string"
      }
    }
  }
}

List webhooks

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/webhook/list

Lists the merchant's webhook endpoints with optional pagination and a status filter. Returns items and totalCount. The signingSecret is never included.

Authorization: merchantAuth

Body required

application/json
paginationobject
filtersobject

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /merchant/webhook/list
cURL
curl -X POST "$BASE_URL/merchant/webhook/list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "pagination": {
    "limit": 20,
    "skip": 0
  },
  "filters": {
    "status": "active"
  }
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "items": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "url": "string",
          "scope": {
            "type": null
          },
          "events": [
            "payment.status.updated"
          ],
          "status": "active",
          "label": "Front desk",
          "createdAt": 1718012345,
          "updatedAt": 1718012345
        }
      ],
      "totalCount": 0
    }
  }
}

Get webhook

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/webhook/get

Fetches a single webhook endpoint by webhookId. The signingSecret is not returned, rotate it to obtain a new one.

Authorization: merchantAuth

Body required

application/json
webhookIdstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /merchant/webhook/get
cURL
curl -X POST "$BASE_URL/merchant/webhook/get" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "webhookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "webhook": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "url": "string",
        "scope": {
          "type": "merchant"
        },
        "events": [
          "payment.status.updated"
        ],
        "status": "active",
        "label": "Front desk",
        "createdAt": 1718012345,
        "updatedAt": 1718012345
      }
    }
  }
}

Update webhook

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/webhook/update

Updates the url, scope, events, status (active / disabled), and/or label of the webhook identified by webhookId. Returns the updated endpoint; the signingSecret is not re-issued.

Authorization: merchantAuth

Body required

application/json
webhookIdstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
urlstring

Destination URL that receives webhook deliveries.

Example:string
scopeobject

Which payments this endpoint receives: merchant (whole account), or store / pos to narrow delivery to one store or terminal.

eventsenum[]

Event types this endpoint is subscribed to.

statusenum

Current status. Payments: initiated / detected / paid / failed / expired / canceled / cleared. Payment transactions: success / failed / pending / cleared.

activedisabled
Example:active
labelstring

Human-readable label for the POS terminal (optional).

Example:Front desk

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /merchant/webhook/update
cURL
curl -X POST "$BASE_URL/merchant/webhook/update" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "webhookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "string",
  "scope": {
    "type": "merchant"
  },
  "events": [
    "payment.status.updated"
  ],
  "status": "active",
  "label": "Front desk"
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "webhook": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "url": "string",
        "scope": {
          "type": "merchant"
        },
        "events": [
          "payment.status.updated"
        ],
        "status": "active",
        "label": "Front desk",
        "createdAt": 1718012345,
        "updatedAt": 1718012345
      }
    }
  }
}

Delete webhook

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/webhook/delete

Deletes the webhook endpoint identified by webhookId. Returns { ok }.

Authorization: merchantAuth

Body required

application/json
webhookIdstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /merchant/webhook/delete
cURL
curl -X POST "$BASE_URL/merchant/webhook/delete" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "webhookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "ok": true
    }
  }
}

Rotate webhook secret

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/webhook/rotate-secret

Rotates the signing secret for the webhook identified by webhookId, invalidating the previous secret and returning a fresh signingSecret (shown only once).

Authorization: merchantAuth

Body required

application/json
webhookIdstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /merchant/webhook/rotate-secret
cURL
curl -X POST "$BASE_URL/merchant/webhook/rotate-secret" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "webhookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "signingSecret": "string"
    }
  }
}

Send test event

POSThttps://api.gobtcpay.com/public/api/v1.2/merchant/webhook/test

Dispatches a sample payment.status.updated delivery to the endpoint identified by webhookId so you can verify your receiver and signature validation. Returns { ok } once the test delivery is queued.

Authorization: merchantAuth

Body required

application/json
webhookIdstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /merchant/webhook/test
cURL
curl -X POST "$BASE_URL/merchant/webhook/test" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "webhookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "ok": true
    }
  }
}