{ "paths": { "/api/v1/stores/{storeId}/webhooks": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store id", "schema": { "type": "string" } } ], "get": { "tags": [ "Webhooks" ], "summary": "Get webhooks of a store", "description": "View webhooks of a store", "operationId": "Webhooks_GetWebhooks", "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDataList" } } } }, "404": { "description": "The key is not found for this list of webhooks" } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] }, "post": { "operationId": "Webhooks_CreateWebhook", "tags": [ "Webhooks" ], "summary": "Create a new webhook", "description": "Create a new webhook", "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDataCreate" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Information about the new webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDataCreate" } } } }, "400": { "description": "A list of errors that occurred when creating the webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/webhooks/{webhookId}": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store id", "schema": { "type": "string" } }, { "name": "webhookId", "in": "path", "required": true, "description": "The webhook id", "schema": { "type": "string" } } ], "get": { "tags": [ "Webhooks" ], "summary": "Get a webhook of a store", "description": "View webhook of a store", "operationId": "Webhooks_GetWebhook", "responses": { "200": { "description": "A webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookData" } } } }, "404": { "description": "The webhook has not been found" } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] }, "put": { "operationId": "Webhooks_UpdateWebhook", "tags": [ "Webhooks" ], "summary": "Update a webhook", "description": "Update a webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDataUpdate" } } }, "required": true, "x-position": 1 }, "responses": { "200": { "description": "Information about the updated webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookData" } } } }, "400": { "description": "A list of errors that occurred when creating the webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] }, "delete": { "operationId": "Webhooks_DeleteWebhook", "tags": [ "Webhooks" ], "summary": "Delete a webhook", "description": "Delete a webhook", "responses": { "200": { "description": "The webhook has been deleted" }, "404": { "description": "The webhook does not exist" } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/webhooks/{webhookId}/deliveries": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store id", "schema": { "type": "string" } }, { "name": "webhookId", "in": "path", "required": true, "description": "The webhook id", "schema": { "type": "string" } } ], "get": { "operationId": "Webhooks_GetWebhookDeliveries", "tags": [ "Webhooks" ], "summary": "Get latest deliveries", "description": "List the latest deliveries to the webhook, ordered from the most recent", "parameters": [ { "name": "count", "in": "query", "description": "The number of latest deliveries to fetch", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of deliveries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } }, "404": { "description": "The key is not found for this list of deliveries" } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/webhooks/{webhookId}/deliveries/{deliveryId}": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store id", "schema": { "type": "string" } }, { "name": "webhookId", "in": "path", "required": true, "description": "The webhook id", "schema": { "type": "string" } }, { "name": "deliveryId", "in": "path", "required": true, "description": "The id of the delivery", "schema": { "type": "string" } } ], "get": { "operationId": "Webhooks_GetWebhookDelivery", "tags": [ "Webhooks" ], "summary": "Get a webhook delivery", "description": "Information about a webhook delivery", "responses": { "200": { "description": "Information about a delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryData" } } } }, "404": { "description": "The delivery does not exists." } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/webhooks/{webhookId}/deliveries/{deliveryId}/request": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store id", "schema": { "type": "string" } }, { "name": "webhookId", "in": "path", "required": true, "description": "The webhook id", "schema": { "type": "string" } }, { "name": "deliveryId", "in": "path", "required": true, "description": "The id of the delivery", "schema": { "type": "string" } } ], "get": { "operationId": "Webhooks_GetWebhookDeliveryRequests", "tags": [ "Webhooks" ], "summary": "Get the delivery's request", "description": "The delivery's JSON request sent to the endpoint", "responses": { "200": { "description": "The delivery's JSON Request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "The delivery does not exists." } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] } }, "/api/v1/stores/{storeId}/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver": { "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "The store id", "schema": { "type": "string" } }, { "name": "webhookId", "in": "path", "required": true, "description": "The webhook id", "schema": { "type": "string" } }, { "name": "deliveryId", "in": "path", "required": true, "description": "The id of the delivery", "schema": { "type": "string" } } ], "post": { "operationId": "Webhooks_RedeliverWebhookDelivery", "tags": [ "Webhooks" ], "summary": "Redeliver the delivery", "description": "Redeliver the delivery", "responses": { "200": { "description": "The new delivery id being broadcasted. (Broadcast happen asynchronously with this call)", "content": { "application/json": { "schema": { "type": "string" } } } }, "404": { "description": "The delivery does not exists." } }, "security": [ { "API_Key": [ "btcpay.store.webhooks.canmodifywebhooks" ], "Basic": [] } ] } } }, "components": { "schemas": { "WebhookDeliveryList": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryData" } }, "WebhookDeliveryData": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the delivery", "nullable": false }, "timestamp": { "nullable": false, "description": "Timestamp of when the delivery got broadcasted", "allOf": [ { "$ref": "#/components/schemas/UnixTimestamp" } ] }, "httpCode": { "type": "number", "description": "HTTP code received by the remote service, if any.", "nullable": true }, "errorMessage": { "type": "string", "description": "User friendly error message, if any." }, "status": { "type": "string", "description": "Whether the delivery failed or not (possible values are: `Failed`, `HttpError`, `HttpSuccess`)" } } }, "WebhookDataList": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookData" } }, "WebhookData": { "allOf": [ { "$ref": "#/components/schemas/WebhookDataBase" }, { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the webhook", "nullable": false } } } ] }, "WebhookDataCreate": { "allOf": [ { "$ref": "#/components/schemas/WebhookData" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Must be used by the callback receiver to ensure the delivery comes from BTCPay Server. BTCPay Server includes the `BTCPay-Sig` HTTP header, whose format is `sha256=HMAC256(UTF8(webhook's secret), body)`. The pattern to authenticate the webhook is similar to [how to secure webhooks in Github](https://docs.github.com/webhooks/securing/).", "nullable": false } } } ] }, "WebhookDataUpdate": { "allOf": [ { "$ref": "#/components/schemas/WebhookDataBase" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Must be used by the callback receiver to ensure the delivery comes from BTCPay Server. BTCPay Server includes the `BTCPay-Sig` HTTP header, whose format is `sha256=HMAC256(UTF8(webhook's secret), body)`. The pattern to authenticate the webhook is similar to [how to secure webhooks in Github](https://docs.github.com/webhooks/securing/). If left out, null, or empty, the secret will not be changed.", "nullable": true } } } ] }, "WebhookDataBase": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The id of the webhook", "nullable": false }, "enabled": { "type": "boolean", "description": "Whether this webhook is enabled or not", "nullable": false, "default": true }, "automaticRedelivery": { "type": "boolean", "description": "If true, BTCPay Server will retry to redeliver any failed delivery after 10 seconds, 1 minutes and up to 6 times after 10 minutes.", "nullable": false, "default": true }, "url": { "type": "string", "description": "The endpoint where BTCPay Server will make the POST request with the webhook body", "nullable": false }, "authorizedEvents": { "type": "object", "description": "Which event should be received by this endpoint", "properties": { "everything": { "type": "boolean", "description": "If true, the endpoint will receive all events related to the store.", "nullable": false, "default": true }, "specificEvents": { "type": "array", "items": { "type": "string" }, "description": "If `everything` is false, the specific events that the endpoint is interested in. Current events are: `InvoiceCreated`, `InvoiceReceivedPayment`, `InvoiceProcessing`, `InvoiceExpired`, `InvoiceSettled`, `InvoiceInvalid`.", "nullable": false } } } } }, "WebhookEvent": { "type": "object", "additionalProperties": false, "properties": { "deliveryId": { "type": "string", "nullable": false, "description": "The delivery id of the webhook" }, "webhookId": { "type": "string", "nullable": false, "description": "The id of the webhook" }, "originalDeliveryId": { "type": "string", "nullable": false, "description": "If this delivery is a redelivery, the is the delivery id of the original delivery." }, "isRedelivery": { "type": "boolean", "nullable": false, "description": "True if this delivery is a redelivery" }, "type": { "type": "string", "nullable": false, "description": "The type of this event, current available are `InvoiceCreated`, `InvoiceReceivedPayment`, `InvoiceProcessing`, `InvoiceExpired`, `InvoiceSettled`, `InvoiceInvalid`, and `InvoicePaymentSettled`." }, "timestamp": { "description": "The timestamp when this delivery has been created", "allOf": [ { "$ref": "#/components/schemas/UnixTimestamp" } ] } } }, "WebhookInvoiceEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "storeId": { "type": "string", "description": "The store id of the invoice's event", "nullable": false }, "invoiceId": { "type": "string", "description": "The invoice id of the invoice's event", "nullable": false }, "metadata": { "type": "object", "description": "User-supplied metadata added to the invoice at the time of its creation", "nullable": false } } } ] }, "WebhookInvoiceSettledEvent": { "description": "Callback sent if the `type` is `InvoiceSettled`", "allOf": [ { "$ref": "#/components/schemas/WebhookInvoiceEvent" }, { "type": "object", "properties": { "manuallyMarked": { "type": "boolean", "description": "Whether the invoice have been manually marked as confirmed", "nullable": false } } }, { "type": "object", "properties": { "overPaid": { "type": "boolean", "description": "Whether this invoice has received more money than expected", "nullable": false } } } ] }, "WebhookInvoiceInvalidEvent": { "description": "Callback sent if the `type` is `InvoiceInvalid`", "allOf": [ { "$ref": "#/components/schemas/WebhookInvoiceEvent" }, { "type": "object", "properties": { "manuallyMarked": { "type": "boolean", "description": "Whether the invoice have been manually marked as confirmed. If false, this invoice has received payments which could not confirm in time.", "nullable": false } } } ] }, "WebhookInvoiceProcessingEvent": { "description": "Callback sent if the `type` is `InvoiceProcessing`", "allOf": [ { "$ref": "#/components/schemas/WebhookInvoiceEvent" }, { "type": "object", "properties": { "overPaid": { "type": "boolean", "description": "Whether this invoice has received more money than expected", "nullable": false } } } ] }, "WebhookInvoiceReceivedPaymentEvent": { "description": "Callback sent if the `type` is `InvoiceReceivedPayment`", "allOf": [ { "$ref": "#/components/schemas/WebhookInvoiceEvent" }, { "type": "object", "properties": { "afterExpiration": { "type": "boolean", "description": "Whether this payment has been sent after expiration of the invoice", "nullable": false }, "paymentMethod": { "type": "string", "description": "What payment method was used for this payment", "nullable": false }, "payment": { "description": "Details about the payment", "$ref": "#/components/schemas/Payment" } } } ] }, "WebhookInvoicePaymentSettledEvent": { "description": "Callback sent if the `type` is `InvoicePaymentSettled`", "allOf": [ { "$ref": "#/components/schemas/WebhookInvoiceReceivedPaymentEvent" } ] }, "WebhookInvoiceExpiredEvent": { "description": "Callback sent if the `type` is `InvoiceExpired`", "allOf": [ { "$ref": "#/components/schemas/WebhookInvoiceEvent" }, { "type": "object", "properties": { "partiallyPaid": { "type": "boolean", "description": "Whether the invoice received some payments before being expired.", "nullable": false } } } ] } } }, "x-webhooks": { "InvoiceCreated": { "post": { "operationId": "Webhook_InvoiceCreated", "summary": "InvoiceCreated", "description": "A new invoice has been created", "parameters": [ { "in": "header", "name": "BTCPay-Sig", "required": true, "description": "The HMAC of the body's byte with the secret's of the webhook. `sha256=HMAC256(UTF8(webhook's secret), body)`", "schema": { "type": "string", "example": "sha256=b438519edde5c8144a4f9bcec51a9d346eca6506887c2ceeae1c0092884a97b9" } } ], "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvoiceEvent" } } } }, "responses": { "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "InvoiceExpired": { "post": { "operationId": "Webhook_InvoiceExpired", "summary": "InvoiceExpired", "description": "An invoice expired", "parameters": [ { "in": "header", "name": "BTCPay-Sig", "required": true, "description": "The HMAC of the body's byte with the secret's of the webhook. `sha256=HMAC256(UTF8(webhook's secret), body)`", "schema": { "type": "string", "example": "sha256=b438519edde5c8144a4f9bcec51a9d346eca6506887c2ceeae1c0092884a97b9" } } ], "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvoiceExpiredEvent" } } } }, "responses": { "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "InvoiceReceivedPayment": { "post": { "operationId": "Webhook_InvoiceReceivedPayment", "summary": "InvoiceReceivedPayment", "description": "An invoice received a payment", "parameters": [ { "in": "header", "name": "BTCPay-Sig", "required": true, "description": "The HMAC of the body's byte with the secret's of the webhook. `sha256=HMAC256(UTF8(webhook's secret), body)`", "schema": { "type": "string", "example": "sha256=b438519edde5c8144a4f9bcec51a9d346eca6506887c2ceeae1c0092884a97b9" } } ], "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvoiceReceivedPaymentEvent" } } } }, "responses": { "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "InvoicePaymentSettled": { "post": { "operationId": "Webhook_InvoicePaymentSettled", "summary": "InvoicePaymentSettled", "description": "An payment relating to an invoice has settled", "parameters": [ { "in": "header", "name": "BTCPay-Sig", "required": true, "description": "The HMAC of the body's byte with the secret's of the webhook. `sha256=HMAC256(UTF8(webhook's secret), body)`", "schema": { "type": "string", "example": "sha256=b438519edde5c8144a4f9bcec51a9d346eca6506887c2ceeae1c0092884a97b9" } } ], "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvoicePaymentSettledEvent" } } } }, "responses": { "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "InvoiceProcessing": { "post": { "operationId": "Webhook_InvoiceProcessing", "summary": "InvoiceProcessing", "description": "Triggers when an invoice is fully paid, but doesn't have the required amount of confirmations on the blockchain yet according to your store's settings.", "parameters": [ { "in": "header", "name": "BTCPay-Sig", "required": true, "description": "The HMAC of the body's byte with the secret's of the webhook. `sha256=HMAC256(UTF8(webhook's secret), body)`", "schema": { "type": "string", "example": "sha256=b438519edde5c8144a4f9bcec51a9d346eca6506887c2ceeae1c0092884a97b9" } } ], "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvoiceProcessingEvent" } } } }, "responses": { "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "InvoiceInvalid": { "post": { "operationId": "Webhook_InvoiceInvalid", "summary": "InvoiceInvalid", "description": "An invoice became invalid", "parameters": [ { "in": "header", "name": "BTCPay-Sig", "required": true, "description": "The HMAC of the body's byte with the secret's of the webhook. `sha256=HMAC256(UTF8(webhook's secret), body)`", "schema": { "type": "string", "example": "sha256=b438519edde5c8144a4f9bcec51a9d346eca6506887c2ceeae1c0092884a97b9" } } ], "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvoiceInvalidEvent" } } } }, "responses": { "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "InvoiceSettled": { "post": { "operationId": "Webhook_InvoiceSettled", "summary": "InvoiceSettled", "description": "Triggers when an invoice is considered settled and the merchant can proceed with the order's delivery. The invoice now has enough confirmations on the blockchain (if paid on-chain) according to your store's configuration.", "parameters": [ { "in": "header", "name": "BTCPay-Sig", "required": true, "description": "The HMAC of the body's byte with the secret's of the webhook. `sha256=HMAC256(UTF8(webhook's secret), body)`", "schema": { "type": "string", "example": "sha256=b438519edde5c8144a4f9bcec51a9d346eca6506887c2ceeae1c0092884a97b9" } } ], "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvoiceSettledEvent" } } } }, "responses": { "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } }, "tags": [ { "name": "Webhooks", "description": "Webhook operations" } ] }