Webhook User Guide

Use webhooks to notify your application about payment events.

What is a webhook?

BaygelPay uses webhooks to push real-time notifications to you about your payments, subscriptions and refund. All webhooks use HTTPS and deliver a JSON payload that can be used by your application.

You can use webhook feeds to do things like:

Automatically enable access to a user after a successful payment
Automatically remove access to a user after a canceled subscription
Confirm that a payment has been received by the same customer that initiated it.

When you will receive a webhook?

Upon events such as successful payment, payment failure, subscription trial initiation, subscription payment success, or refund issuance, BagelPay will automatically send a webhook event to the registered webhook endpoint.

If your endpoint fails to receive the webhooks successfully, BagelPay will automatically attempt to resend the request 6 times at 60-second intervals.

If your webhook endpoint is interrupted unexpectedly, the webhook events that were not sent successfully will be saved in the message queue. When you reactivate the webhook endpoint, bagelpay will continue to send the historical messages in the message queue to the webhook endpoint url before the modification.

Steps to receive a webhook

You can start receiving real-time events in your app using the steps:

Create a endpoint to receive requests

In your local application, create a new roue that can accept POST requests.

For example, you can add an API route on Python.

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
import uvicorn
from pyngrok import ngrok
app = FastAPI()


@app.post("/api/webhooks")
async def handle_post(request: Request):
    try:
        payload = await request.json()
        print(payload)
        return JSONResponse(status_code=200, content={"message": "Success"})
    except Exception as e:
        print(f"Error: {e}")
        return JSONResponse(status_code=400, content={"error": "Invalid request body"})


if __name__ == "__main__":
    listening_port = 8000
    public_url = ngrok.connect(listening_port)
    print(f"ngrok Public URL: {public_url}")
    uvicorn.run(app, host="0.0.0.0", port=listening_port)

On receiving an event, you should respond with an HTTP 200 OK to signal to BagelPay that the event was successfully delivered.

You can create a tunnel to your localhost server using a tool like ngrok. For example:

https://8975b5d4111c.ngrok-free.app/api/webhooks

Register your webhook endpoint in dashboard

On the top navbar, navigate to the “Developer” section.

Click on the "Create webhook" button in the "Webhooks" tab.

Webhook Name: Used to identify your webhook in the platform.
Webhook URL: The URL that will receive the webhook payloads sent by bagelpay.io

Test that your webhook endpoint is working properly

In order to test your webhook endpoint, you could create a checkout session first.

Click the Copy Product ID, get the product_id.

Copy the API Key.

Example command for creating a checkout session.

curl --request POST \
  --url https://test.bagelpay.io/api/payments/checkouts \
  --header 'x-api-key: bagel_dev_C2FEFCD652C740C599A3B6B40FD39BD2' \
  --header 'Content-Type: application/json' \
  --data '{
    "product_id": "prod_1960616428193214466",
    "request_id": "request_12345678",
    "units": 1,
    "customer": {
        "email": "user@example.com"
    },
    "metadata": {
        "key_1": "value_1",
        "key_2": "value_1",
        "key_N": "value_N"
    }
}'