Webhook Resource

A resource designed to notify you about specific state changes of another resource via an HTTP call to your preconfigured URL.

Pouch will generate a signature using HMAC-SHA256 and assign it to the X-Pouch-Signature header per webhook event. A POST request will be sent to the webhook url and expecting a 2xx response from the client.

Events

Type	Description
lightning-invoice.completed	triggers when an invoice status transitions to completed
lightning-payment.completed	triggers when a payment to an invoice is completed
lightning-payment.failed	triggers when a payment to an invoice failed
onchain-deposit.completed	triggers when an onchain deposit is completed
internal-credit.completed	triggers when an internal credit transfer is completed

To verify the signature:

1. You need to extract the X-Pouch-Signature in the header upon receiving the request

2. Parse the request body to a JSON-string and compute the signature with HMAC-SHA256 and your secret key

3. Compare the generated hash against the value in X-Pouch-Signature

Event Payload

{
  "id": "25a3a581-f163-4652-b848-bff19b020fc8",
  "event": "lightning-invoice.completed",
  "payload": {
    "id": "70a1e5f9-4a4a-4332-bf53-c641208d7b96",
    "walletId": "61ccc621-2811-43c6-b47e-b1f3428850e0",
    "referenceId": "985c2a9f-871e-48d2-8f7a-8cf9bfdb6ec4",
    "currency": "SAT",
    "type": "lightning-invoice",
    "status": "completed",
    "description": "test",
    "paymentRequest": "lntb100u1pj472plpp57jdnj7543vvwzh6uwfx3wx52yg6q87u8u469g80p34znefkj6u6qdq8w3jhxaqcqzpgxqzrcsp56f78ep8vwg9fysgtu9p23nwc7xvlfpukx3ljy4wq756fzzwrrksq9qyyssqp0a26uwpexa76xvrx2swg5snftc9rqz8tf873xyjwa27fzxlm0vy5azyhfsq9h97p5ljkfwjm3r7uxjsuqqmg4520r3hydahntgfywgp48jflp",
    "amount": 10000,
    "fees": [
      {
        "type": "processingFee",
        "amount": 75
      }
    ],
    "total": 9925,
    "remarks": null,
    "createdAt": "2023-11-23T10:24:00.179Z",
    "updatedAt": "2023-11-23T10:24:16.668Z"
  }
}

Retry Strategy

If we received a non-2xx response, we'll re-schedule the webhook to be delivered up to 4 more times with an exponential 30 minute delay.

Example:

Run	Timestamp
0	08-02-2023 1:00:00:000 UTC
1	08-02-2023 1:30:00:000 UTC
2	08-02-2023 2:30:00:000 UTC
3	08-02-2023 4:30:00:000 UTC
4	08-02-2023 8:30:00:000 UTC