Certificates Service (CS) Webhooks

Provides operations to manage certificates.

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

ElectronicSealActivatedPayload

Defines the payload for electronic seals owners webhooks.

^ Back to top

ElectronicSealDeactivatedPayload

Defines the payload for electronic seals owners webhooks.

^ Back to top

ElectronicSealParentPayload

Defines the payload for electronic seals parent owners webhooks.

^ Back to top

ElectronicSealSignatureCompletedPayload

Defines the payload for electronic seals owners webhooks.

^ 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