Notifications

Notification API Documentation

Overview

The notification mechanism in our API is a crucial component for tracking the progress and outcomes of Image Generation Tasks. Notifications are essential for receiving feedback on task statuses and ensuring seamless communication between the API and client applications.

Why Notifications Are Important

inNotification channels are vital because they provide feedback on the results of image generation tasks. Before using the API, at least one notification channel must be configured from the available types (webhook or RabbitMQ). Among these, webhook is recommended, as it aligns with our internal solutions.

Without an active notification channel, a client application cannot initiate any image generation requests and will encounter the following error:

{
    "errors": {
        "engine: Active": [
            "No active notification channel configurations found for Application d5eabbb8-c0f6-4640-94fd-3566edad499f."
        ],
        "business: Active": [
            "Error getting active notification channel configurations for Application: d5eabbb8-c0f6-4640-94fd-3566edad499f"
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more errors occurred.",
    "status": 404,
    "detail": null,
    "instance": null,
    "extensions": {
        "traceId": "00-ac4f3a19e10981f5f4b5aa22ffd0d0f4-60f1194e0090da68-00"
    }
}

Notification Channel Features

When defining notification channels, it is optional to include the generated image data in the notification message content. Alternatively, the notification can simply provide task completion updates.

  • Important: If the parameter includeImageData is set to true, the generated image data will be included in the notification message content. Otherwise, the notification will provide only task completion updates without including the image data.

A client application can define multiple notification channels of different types (webhook, RabbitMQ).

Task Notifications

The API sends two types of notifications:

  1. An "Image Generation Task Completed" message when an individual task is finished.

  2. An "Image Generation Progress" message when all tasks are completed.

Creating, Updating, and Managing Notifications

Using the provided endpoints, a client application can:

  • Create notification channels

  • Update notification channels

  • Delete notification channels

  • List all or active notification channels defined for the client application

Authentication Requirements

Each request made by a client application to the API must include:

  • A valid JWT token

  • x-api-key and x-api-secret values defined by AdCreative and provided to the client application. These values also carry information about the API usage credits.

If these authentication values are missing, the following error will be returned:

{
  "errors": {
      "business:": [
          "Token is missing, invalid or ApplicationId is not found in the token."
      ]
  },
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more errors occurred.",
  "status": 401,
  "detail": null,
  "instance": null,
  "extensions": {
      "traceId": "00-fc878634896257c5991ac5399ab6c46c-416e4be3606fdbaa-00"
  }
}

This section provides a foundational understanding of how the notification mechanism operates and the prerequisites for its effective use. The next section will detail the available endpoints, including their request and response structures.

Notification Query Endpoints

1. Get All Notification Channel Configurations

Endpoint

GET /api/v1/Notification/ChannelConfiguration/All

Description

Retrieves a list of all notification channel configurations associated with a specific application.

Request

GET /api/v1/Notification/ChannelConfiguration/All?applicationId={applicationId} HTTP/1.1
Host: localhost:9061
Accept: application/json

Query Parameters

  • applicationId (required): The unique identifier of the application.

Example Request

GET /api/v1/Notification/ChannelConfiguration/All?applicationId=d5eabbb8-c0f6-4640-94fd-3566edad499f

Example Response

[
  {
    "id": "e12fb790-ab01-4ae8-9a5a-f996579aaabf",
    "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
    "channel": 2,
    "notificationChannelConfigurationJSON": "{\"Url\":\"amqp://localhost/Test/\",\"Username\":\"guestRabbit\",\"Password\":\"2w3e3e4r5t\",\"QueueName\":\"queueTest\"}",
    "notificationChannelConfiguration": {
      "isActive": false,
      "includeImageData": true,
      "notificationChannel": 2
    },
    "isActive": false,
    "includeImageData": true,
    "createdAt": "2024-07-17T09:25:58.642536Z",
    "updatedAt": "2024-07-17T09:25:58.642537Z"
  }
]

2. Get Active Notification Channel Configurations

Endpoint

GET /api/v1/Notification/ChannelConfiguration/Active

Description

Retrieves a list of active notification channel configurations for a specific application.

Request

GET /api/v1/Notification/ChannelConfiguration/Active?applicationId={applicationId} HTTP/1.1
Host: localhost:6061
Accept: application/json

Query Parameters

  • applicationId (required): The unique identifier of the application.

Example Request

GET /api/v1/Notification/ChannelConfiguration/Active?applicationId=d5eabbb8-c0f6-4640-94fd-3566edad499f

Example Response (Active Notification Found)

{
  "$id": "1",
  "$values": [
    {
      "id": "c8409979-12ae-4608-8b2c-70c1d7eae696",
      "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
      "channel": 0,
      "notificationChannelConfigurationJSON": "{\"WebHookUrl\":\"https://example.com/webhook\",\"RetryCount\":5,\"ExponentialBackoffFactor\":2.0}",
      "notificationChannelConfiguration": {
        "isActive": true,
        "includeImageData": true,
        "notificationChannel": 0
      },
      "isActive": true,
      "includeImageData": true,
      "createdAt": "2024-12-20T18:24:23.141247Z",
      "updatedAt": "2024-12-20T18:24:23.141432Z"
    }
  ]
}

Example Response (No Active Notification Found)

{
  "errors": {
    "engine: Active": [
      "No active notification channel configurations found for Application d5eabbb8-c0f6-4640-94fd-3566edad499f."
    ],
    "business: Active": [
      "Error getting active notification channel configurations for Application: d5eabbb8-c0f6-4640-94fd-3566edad499f"
    ]
  },
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more errors occurred.",
  "status": 404
}

3. Get Specific Notification Channel Configuration

Endpoint

GET /api/v1/Notification/ChannelConfiguration

Description

Retrieves a specific notification channel configuration by its configuration ID.

Request

GET /api/v1/Notification/ChannelConfiguration?applicationId={applicationId}&configurationId={configurationId} HTTP/1.1
Host: localhost:6061
Accept: application/json

Query Parameters

  • applicationId (required): The unique identifier of the application.

  • configurationId (required): The unique identifier of the configuration.

Example Request

GET /api/v1/Notification/ChannelConfiguration?applicationId=d5eabbb8-c0f6-4640-94fd-3566edad499f&configurationId=c8409979-12ae-4608-8b2c-70c1d7eae696

Example Response

{
  "id": "c8409979-12ae-4608-8b2c-70c1d7eae696",
  "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
  "channel": 0,
  "notificationChannelConfigurationJSON": "{\"WebHookUrl\":\"https://example.com/webhook\",\"RetryCount\":3,\"ExponentialBackoffFactor\":2.0}",
  "notificationChannelConfiguration": {
    "isActive": true,
    "includeImageData": true,
    "notificationChannel": 0
  },
  "isActive": true,
  "includeImageData": true,
  "createdAt": "2024-12-20T18:24:23.141247Z",
  "updatedAt": "2024-12-20T18:47:12.438504Z"
}

4. Delete Notification Channel Configuration

Endpoint

DELETE /api/v1/Notification/ChannelConfiguration

Description

Deletes a specific notification channel configuration by its configuration ID.

Request

DELETE /api/v1/Notification/ChannelConfiguration?applicationId={applicationId}&configurationId={configurationId} HTTP/1.1
Host: localhost:6061
Accept: application/json

Query Parameters

  • applicationId (required): The unique identifier of the application.

  • configurationId (required): The unique identifier of the configuration.

Example Request

DELETE /api/v1/Notification/ChannelConfiguration?applicationId=d5eabbb8-c0f6-4640-94fd-3566edad499f&configurationId=c8409979-12ae-4608-8b2c-70c1d7eae696

Example Response

true

This section provides detailed documentation for the RabbitMQ and WebHook notification configuration endpoints. These endpoints allow client applications to configure notification channels for receiving task completion updates.

RabbitMQ Endpoints

POST /api/v1/Notification/ChannelConfiguration/RabbitMQ

Description Creates a new RabbitMQ notification channel configuration for a specified application.

Request

  • URL: /api/v1/Notification/ChannelConfiguration/RabbitMQ

  • Query Parameters:

    {
  "applicationId": "4e2d4910-d39f-f887-6ec4-b3c82e3c0099"
}

  • Headers:

    {
  "Authorization": "Bearer <token>",
  "x-api-key": "<your-api-key>",
  "x-api-secret": "<your-api-secret>"
}

  • Body (form-data):

    {
  "isActive": true,
  "password": "securePassword123",
  "queueName": "TaskQueue",
  "username": "admin",
  "url": "amqp://localhost/Test",
  "includeImageData": true
}

Example Response

{
    "id": "4d082fcb-2632-47c3-ac16-b92081801c2c",
    "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
    "channel": 2,
    "notificationChannelConfigurationJSON": "{\"Url\":\"amqp://localhost/Test\",\"Username\":\"admin\",\"Password\":\"securePassword123\",\"QueueName\":\"TaskQueue\"}",
    "isActive": true,
    "includeImageData": true,
    "createdAt": "2024-12-20T18:44:43.278369Z",
    "updatedAt": "2024-12-20T18:44:43.278369Z"
}

PUT /api/v1/Notification/ChannelConfiguration/RabbitMQ

Description Updates an existing RabbitMQ notification channel configuration.

Request

  • URL: /api/v1/Notification/ChannelConfiguration/RabbitMQ

  • Query Parameters:

    {
  "applicationId": "4e2d4910-d39f-f887-6ec4-b3c82e3c0099",
  "configurationId": "4d082fcb-2632-47c3-ac16-b92081801c2c"
}

  • Headers:

    {
  "Authorization": "Bearer <token>",
  "x-api-key": "<your-api-key>",
  "x-api-secret": "<your-api-secret>"
}

  • Body (form-data):

    {
  "isActive": true,
  "password": "securePassword123",
  "queueName": "TaskQueue",
  "username": "admin",
  "url": "amqp://localhost/Test",
  "includeImageData": true
}

Example Response

{
    "id": "4d082fcb-2632-47c3-ac16-b92081801c2c",
    "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
    "channel": 2,
    "notificationChannelConfigurationJSON": "{\"Url\":\"amqp://localhost/Test\",\"Username\":\"admin\",\"Password\":\"securePassword123\",\"QueueName\":\"TaskQueue\"}",
    "isActive": true,
    "includeImageData": true,
    "createdAt": "2024-12-20T18:44:43.278369Z",
    "updatedAt": "2024-12-20T18:46:09.637558Z"
}

WebHook Endpoints

POST /api/v1/Notification/ChannelConfiguration/WebHook

Description Creates a new WebHook notification channel configuration for a specified application.

Request

  • URL: /api/v1/Notification/ChannelConfiguration/WebHook

  • Query Parameters:

    {
  "applicationId": "4e2d4910-d39f-f887-6ec4-b3c82e3c0099"
}

  • Headers:

    {
  "Authorization": "Bearer <token>",
  "x-api-key": "<your-api-key>",
  "x-api-secret": "<your-api-secret>"
}

  • Body (form-data):

    {
  "isActive": true,
  "retryCount": 5,
  "webHookUrl": "https://webhook.site/example",
  "exponentialBackoffFactor": 2.0,
  "includeImageData": true
}

Example Response

{
    "id": "d8382f6f-fc70-42aa-99a9-06c1948cd36a",
    "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f",
    "channel": 0,
    "notificationChannelConfigurationJSON": "{\"WebHookUrl\":\"https://webhook.site/example\",\"RetryCount\":5,\"ExponentialBackoffFactor\":2.0}",
    "isActive": true,
    "includeImageData": true,
    "createdAt": "2024-07-30T20:35:26.4982017Z",
    "updatedAt": "2024-07-30T20:35:26.4982468Z"
}

Notes: All API requests must include valid JWT tokens in the header, along with x-api-key and x-api-secret values.

Enum Values in Responses

In the responses, the NotificationChannel property represents the type of notification channel used. This property corresponds to the following enum values:

Enum Value
Integer Representation
Description

WebHook

0

Webhook channel

SignalR

1

SignalR channel

RabbitMQ

2

RabbitMQ channel

Please use these mappings to interpret the NotificationChannel values in the API responses.

PreviousAuthenticationNextHow to Receive Notifications

Last updated