​
What is a Webhook?

A webhook is an HTTP request, triggered by an event in a source system and sent to a destination system, with a payload of data (an event object).

​
Why do we need Webhooks?

You’ll need your website or application to promptly receive events from Chargily Pay as they occur, enabling the execution of corresponding actions.

For example, when a customer successfully pays for an order, your website or application should be informed to update the order status to “Paid.”

To inform your website or application, Chargily Pay sends a webhook, which is a HTTPS POST request with a JSON payload.

​
Example webhook payload

Here is an example of a webhook payload of a successfully paid checkout:

Event Payload Example
{
   "id": "01hjjjzf7wbc454te45mwx35fe",
   "entity": "event",
   "livemode": "false",
   "type": "checkout.paid",
   "data": {
      "id": "01hjjj9aymmrwe664nbzrv84sg",
      "entity": "checkout",
      "fees": 1250,
      "amount": 50000,
      "locale": "ar",
      "status": "paid",
      "metadata": null,
      "created_at": 1703577693,
      "invoice_id": null,
      "updated_at": 1703578418,
      "customer_id": "01hjjjzf07chnbkcjax2vs58fv",
      "description": null,
      "failure_url": null,
      "success_url": "https://your-cool-website.com/payments/success",
      "payment_method": null,
      "payment_link_id": null,
      "pass_fees_to_customer": null,
      "chargily_pay_fees_allocation": "customer",
      "shipping_address": null,
      "collect_shipping_address": 1,
      "discount": null,
      "amount_without_discount": null,
      "url": "https://pay.chargily.dz/test/checkouts/01hjjj9aymmrwe664nbzrv84sg/pay"
   },
   "created_at": 1703578418,
   "updated_at": 1703578418
}

​
The structure of a webhook’s payload

type: The type key in the payload indicates the type of event that occurred, checkout.paid in the previous example which means that the event was triggered by a successfully paid checkout.

data: The data key in the payload contains the object related to the event, the object that triggered the event. In the previous example, the event object is a Checkout.

​
Create your webhook endpoint

You need to set up an endpoint on your backend that accepts POST requests so that Chargily Pay can send you the webhooks.

​
What should your endpoint do

1

Verifying the signature

For security reasons, every webhook request sent to your endpoint from Chargily Pay will have a header called signature, which is a HMAC of the payload signed with your API secret key.
You need to verify it to make sure that the request came from us and that the payload hasn’t been tampered with.

2

Identify the event

Each request’s payload comes with a type key that indicates the type of event that occurred, you can use it to identify the event and take the appropriate action.

3

Handle the event

Once you’ve identified the event, you can handle it by executing the necessary actions.

4

Respond with a 200 response

After you’ve handled the event, you need to respond with a 200 response to let us know that you’ve received the webhook.

​
Example endpoint

Here is an example of a webhook endpoint:

​
Register your endpoint URL

To register your endpoint URL, go to the Developers Corner page in the Chargily Pay Dashboard and add the URL of your endpoint.

Or you can pass the URL of your endpoint in the webhook_url parameter when creating a checkout and we will use it as the endpoint URL for that checkout.

​
Test your webhook endpoint locally

Chargily Pay can’t send webhooks to your local server, so to test your webhook endpoint locally, you can use a tool like ngrok to make your local endpoint publicly accessible.

Account verificationFees