Applications Service (APPS) Webhooks

The Applications service is responsible for managing applications and technical configurations for Cegid products. This service belongs to the Juice family of services.

Index

• Events
• Payloads
• Operations
  • Create Subscription
  • Update Subscription
  • Delete Subscription
  • Get Webhooks Metadata
  • Get Subscription
  • Get Subscriptions
  • Delete Subscriptions
  • Ping Subscription
• Callbacks
• Dead-lettering

Events

^ Back to top

Payloads

ACLEntries

Describes an acl entries.

^ Back to top

AppDefinition

Defines an application definition.

^ Back to top

AppDefinitionApiRequiredScopesChanges

Describes an app definition API required scopes changes.

^ Back to top

AppDefinitionChanges

Describes an app definition changes.

^ Back to top

AppDefinitionDependenciesChanges

Describes an app definition dependencies changes.

^ Back to top

AppDefinitionFeaturesChanges

Describes an app definition features changes.

^ Back to top

AppDefinitionResourcesChanges

Describes an app definition resources changes.

^ Back to top

AppDefinitionRolesChanges

Describes an app definition roles changes.

^ Back to top

AppInstance

Defines an application instance.

^ Back to top

AppInstanceCompany

Describes an app instance company.

^ Back to top

AppInstanceStateChangedPayload

Describes an app instance state changed payload.

^ Back to top

EntityDeletedPayload

The payload to send on a entity deleted event.

^ Back to top

Organization

Defines an organization.

^ Back to top

RolesAssignments

Describes a roles assignments.

^ Back to top

Workspace

Defines a workspace.

^ Back to top

Operations

The REST API provides endpoints that allow creating, updating, and deleting subscriptions to specific events.

Create Subscription

Creates a subscription for one or more webhooks events.

Parameters

Result

The subscription identifier, which can latter be used to update, delete it, etc.

Example (HTTP)

POST /api/v{version:apiVersion}/webhooks
content-type: application/json
body:
{
  "clientId": "{ClientId}",
  "eventNames": [
    "{EventName}
  ],
  "callbackUrl": "{CallbackUrl}",
  "secret": "{Secret}",
  "deadLettering": {
    "enabled": false,
    "configuration": null
  },
  "active": true
}

Example (Client Library)

CreateWebhookSubscriptionRequest request = new CreateWebhookSubscriptionRequest()
{
  (...)
};

try
{
  RestServiceResult<string> result = await this.ServiceClient.Webhooks.CreateSubscriptionAsync(request).ConfigureAwait(false);

  string subscriptionId = result.Value;

  (...)
}
catch (RestRequestException ex)
{
  (...)
}

^ Back to top

Update Subscription

Updates an existing subscription.

Parameters

Example (HTTP)

PUT /api/v{version:apiVersion}/webhooks
content-type: application/json
body:
{
  "subscriptionId": "{SubscriptionId}",
  "clientId": "{ClientId}",
  "eventNames": [
    "{EventName}
  ],
  "callbackUrl": "{CallbackUrl}",
  "secret": "{Secret}",
  "deadLettering": {
    "enabled": false,
    "configuration": null
  },
  "active": true
}

Example (Client Library)

UpdateWebhookSubscriptionRequest request = new UpdateWebhookSubscriptionRequest()
{
  (...)
};

try
{
  RestServiceResult result = await this.ServiceClient.Webhooks.UpdateSubscriptionAsync(request).ConfigureAwait(false);

  (...)
}
catch (RestRequestException ex)
{
  (...)
}

^ Back to top

Delete Subscription

Deletes an existing subscription.

Parameters

Example (HTTP)

DELETE /api/v{version:apiVersion}/webhooks/{clientId}/{subscriptionId}

Example (Client Library)

try
{
  RestServiceResult result = await this.ServiceClient.Webhooks.DeleteSubscriptionAsync("{ClientId}", "{SubscriptionId}").ConfigureAwait(false);

  (...)
}
catch (RestRequestException ex)
{
  (...)
}

^ Back to top

Get Webhooks Metadata

Retrieves metadata about all the webhooks available.

Result

The webhooks metadata.

[
  {
    "eventName": "{EventName}",
    "eventDescription": "{EventDescription}",
    "PayloadDescription": "{PayloadDescription}"
  }
]

Example (HTTP)

GET /api/v{version:apiVersion}/webhooks

Example (Client Library)

try
{
  RestServiceResult<IList<WebhookMetadata>> result = await this.ServiceClient.Webhooks.GetWebhooksMetadataAsync().ConfigureAwait(false);

  IList<WebhookMetadata> metadata = result.Value;

  (...)
}
catch (RestRequestException ex)
{
  (...)
}

^ Back to top

Get Subscription

Retrieves a subscription.

Parameters

Result

The subscription information.

{
  "clientId": "{ClientId}",
  "subscriptionId": "{SubscriptionId}",
  "eventNames": ["{EventName1}", "{EventName2}"],
  "secret": "{Secret}",
  "callbackUrl": "{CallbackUrl}",
  "filters": {
    "{Filter1}": "{Value1}",
    "{Filter2}": "{Value2}"
  },
  "properties": {
    "{Property1}": "{Value1}",
    "{Property2}": "{Value2}"
  },
  "deadLettering": {
    "enabled": true,
    "configuration": "{Configuration}"
  },
  "active": true,
  "modifiedOn": {ModifiedOn},
  "lastRequest": {
    (...)
  },
  "lastResponse": {
    (...)
  }
}

Example (HTTP)

GET /api/v{version:apiVersion}/webhooks/{clientId}/{subscriptionId}

Example (Client Library)

try
{
  RestServiceResult<WebhookSubscription> result = await this.ServiceClient.Webhooks.GetSubscriptionAsync("{ClientId}", "{SubscriptionId}").ConfigureAwait(false);

  WebhookSubscription subscription = result.Value;

  (...)
}
catch (RestRequestException ex)
{
  (...)
}

^ Back to top

Get Subscriptions

Retrieves all the subscriptions for a given client.

Parameters

Result

A list containing the subscriptions information (as in Get Subscription).

Example (HTTP)

GET /api/v{version:apiVersion}/webhooks/{clientId}

Example (Client Library)

try
{
  RestServiceResult<IList<WebhookSubscription>> result = await this.ServiceClient.Webhooks.GetSubscriptionsAsync("{ClientId}").ConfigureAwait(false);

  IList<WebhookSubscription> subscriptions = result.Value;

  (...)
}
catch (RestRequestException ex)
{
  (...)
}

^ Back to top

Delete Subscriptions

Deletes all the subscriptions for a given client.

Parameters

Example (HTTP)

DELETE /api/v{version:apiVersion}/webhooks/{clientId}

Example (Client Library)

try
{
  RestServiceResult result = await this.ServiceClient.Webhooks.DeleteSubscriptionsAsync("{ClientId}").ConfigureAwait(false);

  (...)
}
catch (RestRequestException ex)
{
  (...)
}

^ Back to top

Ping Subscription

Pings a subscription.

Parameters

Example (HTTP)

POST /api/v{version:apiVersion}/webhooks/{clientId}/{subscriptionId}/ping

Example (Client Library)

try
{
  RestServiceResult result = await this.ServiceClient.Webhooks.PingSubscriptionAsync("{ClientId}", "{SubscriptionId}").ConfigureAwait(false);

  (...)
}
catch (RestRequestException ex)
{
  (...)
}

^ Back to top

Callbacks

When a webhook event occurs, the callback URL will be invoked for all active subscriptions.

This callback is a request to the endpoint configured in the subscription, including the webhook payload in the content.

Additionally, the following headers will be sent in the request, allowing the client application to identify the concrete event and authenticate the request.

^ Back to top

Dead-lettering

If the webhooks server supports dead-lettering, then it can be enabled when creating or updating webhooks subscriptions.

This feature ensures the availability to the client application of all the events occurred, because, when the server is not able to deliver a webhook (for example, if the client is down), after retrying the configured number of times, it will store the event in the blobs storage account provided by the client configuration. The client can inspect this blob storage and recover all the missed events.

The configuration is provided using the DeadLettering.Configuration setting, when creating/updating a subscription. This should be a config string (a string in the form prop1=value;prop2=value) specifying how the server should connect to the storage account, using the following properties:

• ConnectionString (optional) - a connection string for the storage account.
• ServiceUri (optional) - the blob storage service URI.
• TenantId (required if ServiceUri is specified) - the tenant identifier that should be used to authorize against the blob storage service.
• ClientId (required if ServiceUri is specified) - the client identifier that should be used for authorization.
• ClientSecret (required if ServiceUri is specified) - the client secret that should be used for authorization.
• Container (required) - the name of the container that should be used to store the dead-letters.

Notice that you can either specify the connection using ConnectionString OR ServiceUri, TenantId, ClientId, and ClientSecret.

The values passed in for ConnectionString, ServiceUri, TenantId, ClientId, and ClientSecret need to be escaped, by replacing the following chars:

• + replaced with #2B
• ; replaced with #3B
• = replaced with #3D

Each dead-letter will be a JSON file stored in the blob container and named <EventName>-<Timestamp>-<RandomString>.

^ Back to top