​
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: 
import hashlib
import hmac
import json
from django.http import HttpResponse, JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST

# Your Chargily Pay Secret key, will be used to calculate the Signature
api_secret_key = 'test_sk_Fje5EhFwyGTGqk4M6et3Jxxxxxxxxxxxxxxxxxxxx'

@csrf_exempt
@require_POST
def webhook(request):
    # Extracting the 'signature' header from the HTTP request
    signature = request.headers.get('signature')

    # Getting the raw payload from the request body
    payload = request.body.decode('utf-8')

    # If there is no signature, ignore the request
    if not signature:
        return HttpResponse(status=400)

    # Calculate the signature
    computed_signature = hmac.new(api_secret_key.encode('utf-8'), payload.encode('utf-8'), hashlib.sha256).hexdigest()

    # If the calculated signature doesn't match the received signature, ignore the request
    if not hmac.compare_digest(signature, computed_signature):
        return HttpResponse(status=403)

    # If the signatures match, proceed to decode the JSON payload
    event = json.loads(payload)

    # Switch based on the event type
    if event['type'] == 'checkout.paid':
        checkout = event['data']
        # Handle the successful payment.
    elif event['type'] == 'checkout.failed':
        checkout = event['data']
        # Handle the failed payment.

    # Respond with a 200 OK status code to let us know that you've received the webhook
    return JsonResponse({}, status=200)

​
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. Chargily Pay webhook endpoint setting

​
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.