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:

An "Image Generation Task Completed" message when an individual task is finished.
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

Webhook channel

SignalR

SignalR channel

RabbitMQ

RabbitMQ channel

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

PreviousAuthentication NextHow to Receive Notifications

Last updated 1 year ago

hashtagNotification API Documentation

hashtagOverview

hashtagWhy Notifications Are Important

hashtagNotification Channel Features

hashtagTask Notifications

hashtagCreating, Updating, and Managing Notifications

hashtagAuthentication Requirements

hashtagNotification Query Endpoints

hashtag1. Get All Notification Channel Configurations

hashtag2. Get Active Notification Channel Configurations

hashtag3. Get Specific Notification Channel Configuration

hashtag4. Delete Notification Channel Configuration

hashtagRabbitMQ Endpoints

hashtagWebHook Endpoints

hashtagEnum Values in Responses

Notification API Documentation

Overview

Why Notifications Are Important

Notification Channel Features

Task Notifications

Creating, Updating, and Managing Notifications

Authentication Requirements

Notification Query Endpoints

1. Get All Notification Channel Configurations

2. Get Active Notification Channel Configurations

3. Get Specific Notification Channel Configuration

4. Delete Notification Channel Configuration

RabbitMQ Endpoints

WebHook Endpoints

Enum Values in Responses