Webhook Endpoints

Create webhook endpoints to receive real-time notifications of the user's settled invoices.

Want to use webhooks for your own Alby account? create a webhook in our developer dashboard

Create a webhook endpoint

Scope needed: invoices:read

Creates a new webhook endpoint to receive notifications of settled invoices. Settled invoices are sent to the provided url as a POST request. Requests are sent with SVIX.

The endpoint_secret in the response body should be saved by the client in order to verify webhook posts to url. See the SVIX documentation on how to verify requests.

POST https://api.getalby.com/webhook_endpoints

Creates a new webhook endpoint.

Request Body

Name	Type	Description
description	String
url*	String	Webhook URL
filter_types*	String[]	One or more invoice event types to filter webhook events. Supported values are ["invoice.incoming.settled", "invoice.outgoing.settled"]

200: OK

{
    "url": "https://webhook.site/2d10f6a2-8860-48af-8c25-379a3c921d30",
    "description": "An example endpoint",
    "filter_types": [
        "invoice.settled"
    ],
    "created_at": "2023-05-02T07:35:03.867Z",
    "id": "ep_2PECYp6CLXBbAqyFnhbxFUXM2ZR",
    "endpoint_secret": "whsec_QE8DIo3EtwlPmkOGCmxYyAcAxnpArzP/"
}

400: Bad Request

{
    "errors": [
        "ERROR_MESSAGE_HERE"
    ]
}

Example webhook POST payload (Settled Invoice)

{
  "amount": 1,
  "boostagram": null,
  "comment": "",
  "created_at": "2023-11-08T13:13:20.712Z",
  "creation_date": 1699449200,
  "currency": "btc",
  "custom_records": null,
  "description_hash": "9af9c8bea0ba516e5eadb56c1a24f95002d10f9c18edc37d44c2fd646b1715df",
  "destination_alias": "getalby.com",
  "destination_pubkey": "030a58b8653d32b99200a2334cfe913e51dc7d155aa0116c176657a4f1722677a3",
  "expires_at": "2023-11-09T13:13:20.000Z",
  "expiry": 86400,
  "fiat_currency": "USD",
  "fiat_in_cents": 1,
  "first_route_hint_alias": null,
  "first_route_hint_pubkey": null,
  "identifier": "w88Jq8KKxYZ4NTeW1f2VbGBH",
  "keysend_message": null,
  "memo": null,
  "metadata": {},
  "payer_email": null,
  "payer_name": null,
  "payer_pubkey": null,
  "payment_hash": "ba9b70460206c278b29850d0d1e1a6962678466d2fff9aa11ba7598c61ad2e1a",
  "payment_request": "lnbc10n1pj5hztspp5h2dhq3szqmp83v5c2rgdrcdxjcn8s3nd9lle4ggm5avcccdd9cdqhp5ntuu304qhfgkuh4dk4kp5f8e2qpdzruurrkuxl2yct7kg6chzh0scqzzsxqyz5vqsp59vq2anzwwygr5yrf40ht2pnvje0rc8sncfpcqja3el2kuuzwl7gs9qyyssqy0hks0qwcvh74e2rm7sucxapq7vjc75yy6szyzhgdxkrykpyslakpq7kyhl4p0a7j5ukxxrz8wag3skdtlg38px6zkp6686m0ympqecpu302f9",
  "r_hash_str": "ba9b70460206c278b29850d0d1e1a6962678466d2fff9aa11ba7598c61ad2e1a",
  "settled": true,
  "settled_at": "2023-11-08T13:13:21.000Z",
  "state": "SETTLED",
  "type": "incoming",
  "value": 1
}

Example webhook POST payload (Keysend payment)

{
  "amount": 21,
  "boostagram": {
    "action": "boost",
    "app_name": "webln demo",
    "message": "hello from webln",
    "name": "satoshi",
    "sender_name": "bumi",
    "value_msat_total": 21000
  },
  "comment": "hello from webln",
  "created_at": "2023-05-03T08:22:23.030Z",
  "creation_date": 1683102142,
  "currency": "btc",
  "custom_records": {
    "696969": "cWQ5VVgxYVNKUTVMcmkxRWx6U3o=",
    "7629169": "eyJhY3Rpb24iOiJib29zdCIsInZhbHVlX21zYXRfdG90YWwiOjIxMDAwLCJhcHBfbmFtZSI6IndlYmxuIGRlbW8iLCJzZW5kZXJfbmFtZSI6ImJ1bWkiLCJuYW1lIjoic2F0b3NoaSIsIm1lc3NhZ2UiOiJoZWxsbyBmcm9tIHdlYmxuIn0="
  },
  "description_hash": null,
  "expires_at": "2023-05-03T08:37:22.000Z",
  "expiry": 900,
  "fiat_currency": "USD",
  "fiat_in_cents": 1,
  "identifier": "QMYTg3PKDskease4svYJbM28",
  "keysend_message": null,
  "memo": "",
  "metadata": null,
  "payer_name": "bumi",
  "payer_pubkey": null,
  "payment_hash": "0f2e034d7bcd321ae7e0382f4bd29e4562802b41f9f2b301aa2b055a1c638c84",
  "payment_request": "",
  "r_hash_str": "0f2e034d7bcd321ae7e0382f4bd29e4562802b41f9f2b301aa2b055a1c638c84",
  "settled": true,
  "settled_at": "2023-05-03T08:22:22.000Z",
  "state": "SETTLED",
  "type": "incoming",
  "value": 21
}

Get a webhook endpoint

Scope needed: invoices:read

Get details about a created webhook endpoint.

GET https://api.getalby.com/webhook_endpoints/{id}

Gets a webhook endpoint.

Path Parameters

Name	Type	Description
id*	String	The id of the webhook endpoint

200: OK

{
    "url": "https://webhook.site/2d10f6a2-8860-48af-8c25-379a3c921d30",
    "description": "An example endpoint",
    "filter_types": [
        "invoice.settled"
    ],
    "created_at": "2023-05-02T07:35:03.867Z",
    "id": "ep_2PECYp6CLXBbAqyFnhbxFUXM2ZR"
}

404: Not Found

Delete a webhook endpoint

Scope needed: invoices:read

Delete a webhook endpoint to stop receiving notifications of settled invoices.

DELETE https://api.getalby.com/webhook_endpoints/{id}

Deletes a webhook endpoint.

Path Parameters

Name	Type	Description
id*	String	The id of the webhook endpoint

200: OK

{
    "url": "https://webhook.site/2d10f6a2-8860-48af-8c25-379a3c921d30",
    "description": "An example endpoint",
    "filter_types": [
        "invoice.settled"
    ],
    "created_at": "2023-05-02T07:35:03.867Z",
    "id": "ep_2PECYp6CLXBbAqyFnhbxFUXM2ZR"
}

404: Not Found