API

Overview

The Django Action Triggers API allows users to create, update, and manage triggers and actions programmatically. This API is designed to provide flexibility and control over the application’s behaviour, enabling integrations with external systems through webhooks and message brokers.

Setup

To enable the API in your Django project, you need to include the following in your project’s urls.py file:

urlpatterns = [
    ...
    path('api/action-triggers/', include('action_triggers.urls')),
    ...
]

Usage

The Django Action Triggers application allows users to create and manage triggers and actions either through the Django admin interface or via the API.

API Endpoints

The API provides the following endpoints for interacting with triggers:

/api/action-triggers
- GET: Retrieve a list of all triggers.
- POST: Create a new trigger
- PUT: Update an existing trigger
- DELETE: Delete an existing trigger
/api/action-triggers/<trigger_id>
- GET: Retrieve a single trigger by its ID.
- PUT: Update a single trigger
- DELETE: Delete a single trigger

API Specification

Below is an example of the payload structure used when interacting with the API. This structure defines how triggers, webhooks, and message broker actions are configured.

{
  // List of signals objects, e.g., [{"signal": "pre_save"}, {"signal": "post_save"}]
  "config_signals": {"signal": string}[],  // List of signals objects
  "content_types": [
    {
      "app_label": string,  // Django app label, e.g., "myapp"
      "model_name": string  // Model name, e.g., "User"
    }
  ],
  "webhooks"?: [
    {
      "url": string,  // Webhook URL
      "http_method": "GET" | "POST" | "PUT" | "DELETE",  // HTTP method
      "headers"?: {
        [key: string]: string  // Optional headers
      },
      "timeout_secs"?: number  // Optional timeout in seconds
    }
  ],
  "msg_broker_queues"?: [
    {
      "name": string,  // Reference to configured broker
      "conn_details"?: {
        [key: string]: string  // Optional connection details
      },
      "parameters"?: {
        [key: string]: string  // Optional parameters
      }
      "timeout_secs"?: number  // Optional timeout in seconds
    }
  ],
  "active": boolean,  // Whether the trigger is active
  "payload"?: {
    [key: string]: string | dict  // Optional payload for the action
  }
}

API Constraints

When interacting with the API, the following constraints apply:

Field	Constraints
config_signals.signals	Allowed values: pre_save, post_save, pre_delete, post_delete

Field Descriptions

The following fields are available for use in the API:

Field	Constraint	Description
config_signals	{“signal”: string}[]	The list of signals objects that will trigger the action. For example: [{“signal”: “post_save”}].
content_types	object[]	The list of content types that will trigger the action.
content_types.app_label	string	The app label of the model that will trigger the action.
content_types.model_name	string	The model name that will trigger the action.
webhooks	object[] (optional)	The list of webhooks that will be triggered.
webhooks.url	string	The URL of the webhook.
webhooks.http_method	string	The HTTP method of the webhook.
webhooks.headers	object[] (optional)	A key-value pair of headers that will be sent with the webhook. The value can receive the path to a callable that will be evaluated at runtime.
webhooks.timeout_secs	float	The timeout in seconds for the webhook to respond before aborting the request.
msg_broker_queues	object[] (optional)	The list of queues that will be receive the message.
msg_broker_queues.name	string	The name of the queue as defined in settings.py.ACTION_TRIGGERS.brokers
msg_broker_queues.connection_details	object[] (optional)	A key-value pair of connection details that will be used to connect to the broker. The value can receive the path to a callable that will be evaluated at runtime. If not provided, then settings.ACTION_TRIGGERS.brokers.<name>.conn_details will be used instead.
msg_broker_queues.parameters	object[] (optional)	A key-value pair of parameters that will be sent with the message. The value can receive the path to a callable that will be evaluated at runtime. If not provided, then settings.ACTION_TRIGGERS.brokers.<name>.params will be used instead.
msg_broker_queues.timeout_secs	float	The timeout in seconds for the message broker to respond before aborting the request.
active	boolean	Whether the trigger is enabled or not.
payload	object[] (optional)	A Django template like value. If the resulting value after any parsing is JSON-serializable, then the returning payload will be JSON, otherwise, it’ll be just plain text.

Dynamic Value Assignment

Django Action Triggers supports dynamically setting values at runtime. This feature allows you to define paths to callables or variables that will be evaluated dynamically when the trigger is executed.

For more details, refer to the Dynamically Loading Values at Runtime guide.

Examples

Below are examples illustrating how to use the API to create and manage triggers and actions.

For the following examples, we will use the following models:

from django.db import models

class Customer(models.Model):
  name = models.CharField(max_length=255)
  email = models.EmailField()

class Product(models.Model):
    name = models.CharField(max_length=255)
    description = models.TextField()


class Sale(models.Model):
    customer = models.ForeignKey(Customer, on_delete=models.CASCADE)
    product = models.ForeignKey(Product, on_delete=models.CASCADE)
    quantity = models.IntegerField()

Example 1: Trigger a Webhook on Customer Creation, Update, and Deletion

Note

See the webhooks guide for more information on how the webhook action works.

In this example, a trigger is created that sends a POST request to a webhook whenever a Customer model instance is created, updated, or deleted.

{
  "config_signals": [
    {"signal": "post_save"},
    {"signal": "post_delete"}
  ],
  "content_types": [
    {
      "app_label": "myapp",
      "model_name": "Customer"
    }
  ],
  "webhooks": [
    {
      "url": "https://my-webhook.com",
      "http_method": "POST",
      "headers": {
        "Authorization": "Bearer {{ myapp.utils.get_token }}"
      },
      "timeout_secs": 10.0
    }
  ],
  "active": true
}

Example 2: Trigger Webhooks and Send Messages to a Broker on Product and Sale Creation or Update

Note

See the message brokers guide for more information on how the message broker action works.

Note

See the webhooks guide for more information on how the webhook action works.

This example demonstrates how to create a trigger that sends requests to webhooks and messages to a broker when a Product or Sale is created or updated.

{
  "config_signals": [
    {"signal": "post_save"}
  ],
  "content_types": [
    {
      "app_label": "myapp",
      "model_name": "Product"
    },
    {
      "app_label": "myapp",
      "model_name": "Sale"
    }
  ]
  "webhooks": [
    {
      "url": "https://my-webhook.com",
      "http_method": "POST",
      "headers": {
        "Authorization": "Bearer {{ myapp.utils.get_token }}"
      },
      "timeout_secs": 2.25
    },
    {
      "url": "https://my-other-webhook.com",
      "http_method": "POST",
      "headers": {
        "Authorization": "Bearer {{ myapp.utils.get_token }}"
      }
    }
  ],
  "msg_broker_queues": [
    {
      "name": "my-msg-broker-config",
      "parameters": {
        "product_id": "{{ myapp.utils.get_product_id }}"
      },
      "timeout_secs": 5.75
    },
    {
      "name": "my-other-msg-broker-config",
      "parameters": {
        "sale_id": "{{ myapp.utils.get_sale_id }}"
      }
    }
  ],
  "active": true
}

Example 3: Trigger a Webhook When a Sale is Created/Updated Sending Customer and Product Information

Note

See the message brokers guide for more information on how the message broker action works.

Note

See the webhooks guide for more information on how the webhook action works.

The following example illustrates how to create a trigger that will hit a webhook when a new sale is created or updated. The webhook will send the customer name and product name along with a static action.

{
  "config_signals": [
    {"signal": "post_save"}
  ],
  "content_types": [
    {
      "app_label": "myapp",
      "model_name": "Sale"
    }
  ]
  "webhooks": [
    {
      "url": "https://my-webhook.com",
      "http_method": "POST",
      "headers": {
        "Authorization": "Bearer {{ myapp.utils.get_token }}"
      },
      "timeout_secs": 12.25
    }
  ],
  "active": true,
  "payload": {
    "action": "new_sale",
    "customer_name": "{{ instance.customer.name }}",
    "product_name": "{{ instance.product.name }}"
  }
}