Commerce Webhooks

This document provides a comprehensive guide to the webhooks available in the Commerce project. Webhooks enable external systems to receive real-time notifications when specific events occur within the Commerce infrastructure. By leveraging webhooks, developers can automate workflows, synchronize data between different systems, and enhance the overall integration experience.

Webhooks in Commerce are event-driven and provide a mechanism for pushing data to external services whenever predefined events take place. Instead of continuously polling the system for updates, webhooks deliver relevant information as soon as changes occur. This makes them an efficient and scalable solution for real-time integrations.

Each webhook event contains a structured payload with essential details about the triggered event. Subscribers can listen to these events and take appropriate actions based on the received data. Webhooks can be configured using the dj-whisperer package, which provides a streamlined way to manage webhook subscriptions and deliveries.

dj-whisperer

The dj-whisperer package, developed within Akinon, has been released as an open-source project and is available on PyPI:

• PyPI Package: dj-whisperer

• Documentation: dj-whisperer Docs

Through dj-whisperer, you can subscribe to various webhook events in the Commerce system. The official package documentation provides in-depth details on how to configure and utilize webhooks efficiently.

Available Commerce Webhook Events

To use Commerce events and trigger dj-whisperer events, a specific requirement must be met in the Commerce system. An EventMessageDefinition must be defined for each Webhook Event that will be triggered.

To achieve this, the following POST request should be sent to the Commerce API via Omnitron:

curl --location '{omnitron_url}/api/v1/remote/1/event_messages/' \
--header 'Authorization: Token {token}' \
--header 'Content-Type: application/json' \
--data '{
    "event_name": "user_registered",
    "description": "Description",
    "transactional": true,
    "asynchronous": false,
    "url": "http://localhost:8000/dummy/",
    "authentication_config": {
        "auth_type": "basic",
        "username": "username",
        "password": "password"
    }
}'

Parameters:

• event_name: One of the predefined Commerce event names.

• description: Description of the event.

• transactional: If set to true, the process will halt if an error occurs during webhook transmission (e.g., user registration).

• asynchronous: If set to true, the webhook transmission is queued as a Celery task and processed later.

• url: Must match the URL where the webhook event will be sent.

• authentication_config: If authentication is required at the webhook destination, credentials must be provided (currently, dj-whisperer only supports basic authentication).

Commerce currently supports five webhook events:

1. BasketOfferCreatedEvent

event_name: basket_offer_created

This event is triggered when a new campaign, coupon, or discount code is created.

Payload Structure

{
  "pk": 727,
  "label": "Sepette 100 TL ve Üstüne %50+%50 İndirim",
  "promotion": {
    "id": 727,
    "created_date": "2024-09-23T08:30:18.382660Z",
    "modified_date": "2025-01-28T12:20:15.198191Z",
    "translations": null,
    "name": "%50+%50 İndirim",
    "slug": "mc50_50"
  },
  "condition": {
    "id": 727,
    "product_collection": 628,
    "condition_type": "amount",
    "kwargs": {
      "query": [],
      "value": 100,
      "price_type": "unit_price",
      "consume_type": "globally",
      "data_sources": [
        "madame-coco"
      ],
      "sub_conditions": []
    },
    "created_date": "2024-09-23T08:30:18.388607Z",
    "modified_date": "2025-01-28T12:20:15.208973Z",
    "translations": null,
    "upsell_message": "Sepetine {remaining} değerinde ürün daha ekle, %50+%50 indirimi kazan."
  },
  "benefit": {
    "id": 727,
    "product_collection": 628,
    "benefit_type": "percentage",
    "kwargs": {
      "coupon": {},
      "percentage": 75,
      "price_type": "unit_price",
      "consume_type": "globally"
    },
    "created_date": "2024-09-23T08:30:18.391237Z",
    "modified_date": "2025-01-28T12:20:15.214853Z"
  },
  "voucher_code": null,
  "status": "active",
  "is_visible": true,
  "is_visible_on_list": true,
  "start_datetime": "2025-01-06T08:27:00Z",
  "end_datetime": "2025-01-31T06:00:00Z",
  "offer_type": "sitewide",
  "allowed_quantity_per_basket": 1,
  "priority": 2,
  "is_mergable": true,
  "max_usage_per_user": 0,
  "currencies": [
    "try"
  ],
  "max_stock_limit": 0
}

2. BasketOfferUpdatedEvent

event_name: basket_offer_updated

This event is triggered when a campaign, coupon, or discount code is updated. The payload structure is identical to BasketOfferCreatedEvent.

3. UserLoggedInEvent

event_name: user_logged_in

This event is triggered when a user logs into the Commerce system.

Payload Structure

{
  "pk": 71133,
  "username": "hashed_username",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "is_active": true,
  "date_joined": "2024-12-30T10:50:22.024234Z",
  "last_login": "2025-03-21T10:23:25.026743Z",
  "email_allowed": true,
  "sms_allowed": true,
  "gender": null,
  "attributes": {
    "confirm": true,
    "logged_ip": "127.0.0.1",
    "register_client_type": "default"
  },
  "phone": null,
  "user_type": "registered",
  "modified_date": "2025-01-07T13:41:02.975697Z"
}

4. UserUpdatedEvent

event_name: user_updated

This event is triggered when a user updates their information in the Commerce system. Since the last login date is updated when a user logs in, this event is also triggered when a user successfully logs into the system. The payload structure is identical to UserLoggedInEvent.

5. UserRegisteredEvent

event_name: user_registered

This event is triggered when a new user registers in the Commerce system. The payload structure is identical to UserLoggedInEvent.