Skip to main content

API Webhooks​

A webhook is a way for an application to provide other applications with real-time information. In other words, a webhook is a user-defined HTTP callback that is triggered by specific events. When an event occurs, the source application makes an HTTP request to the URL configured for the webhook.

When you create an invoice, you specify a URL parameter named webhook_url. This URL is where Mimbla will send notifications about the invoice's status changes, such as when it is paid.

After you create an invoice, you should receive a response with the invoice details.

{
    "id": "MWtyHVSGIAer",
    "success": true,
    "invoice_url": "https://www.mimbla.com/pay/MWtyHVSGIAer",
    "due_date": "2024-09-30T23:59:59.000000Z",
    "amount": "10",
    "crypto": "ALL",
}

Mimbla is not opinionated about how you handle the webhook on your end.

Ideally it should be something like this:

https://example.com/webhook/id/MWtyHVSGIAer

https://api.example.com/invoice/<my-invoice-id>

Webhook Method​

Once you create an invoice with the webhook_url parameter, Mimbla will send a GET request to the specified URL whenever the invoice status changes to paid.

Responses​

The GET request sent to your webhook_url will not include a body, a parameter, or a header. It will simply be a request to the URL you provided. Mimbla does not in any way tries multiple attempts to deliver the webhook, so it is up to you to ensure that your webhook URL is accessible and can handle the request, if the request fails, Mimbla will not retry sending the webhook. And you are expected to handle the processing of the webhook on your end.

The TOR Network​

Mimbla supports webhooks over the TOR network, providing an additional layer of privacy and security for your webhooks. Therefore, you can use a .onion address as your webhook_url.

Internally, Mimbla will use the TOR network to send the webhook request to your webhook URL so make sure that Cloudflare or any other similar service is not blocking access to your domain address from the TOR network.

Testing Your Webhook URL for the TOR Network​

If you want to test and check if your webhook URL is accesible from the TOR network or the Mimbla servers, please use the torify command to access the URL through the TOR network.

You can test your webhook URL like this:

torify curl https://example.com/webhook/id/MWtyHVSGIAer

You will need to have tor and torify installed on your system. If you don't have them installed, you can install them using your package manager.

Note: Most of the time you can ignore the torify command and just use curl to test your webhook URL, but if you want to ensure that your webhook URL is accessible from the TOR network, you should use torify.