Working with webhooks

Retrieving list of supported hooks

The supported hooks can be retrieved by issuing GET request to https://api-dev.teliasign.com/hooks/v1. The response contains the array of the supported webhook events. The array items contain information about the event along with the payload schema it provides.

Request

GET https://api-dev.teliasign.com/hooks/v1
-H Authorization: Bearer {Retrieved authentication token.}
-H Ocp-Apim-Subscription-Key: {Subscription key which provides access to this API. Found in your Profile.}

Response

[
  {
    "eventType": "signaturerequestcompleted",
    "description": "The signature request has been completed.",
    "payloadSchema": {
      "EventType": "string",
      "Timestamp": "date",
      "EventData": {
        "SignatureRequestId": "guid",
        "TenantId": "guid",
        "DepartmentId": "guid",
        "CreatorId": "guid"
      }
    }
  },
  {
    "eventType": "signatorysigned",
    "description": "The signatory signed the request.",
    "payloadSchema": {
      "EventType": "string",
      "Timestamp": "date",
      "EventData": {
        "SignatoryId": "guid",
        "SignatureRequestId": "guid",
        "TenantId": "guid",
        "DepartmentId": "guid",
        "CreatorId": "guid"
      }
    }
  }
]

Subscribing to events

The example how to subscribe to SignatureRequestCompleted event.

Request

POST https://api-dev.teliasign.com/hooks/v1/subscription
-H Authorization: Bearer {Retrieved authentication token.}
-H Ocp-Apim-Subscription-Key: {Subscription key which provides access to this API. Found in your Profile.}

Request body

{
  "Description": "Notifications for completed signature requests",
  "Uri": "https://your-site.com/notifications",
  "EventType": "SignatureRequestCompleted",
  "Headers": {
    "client-id": "your id",
    "client-secret": "your secret"
  }
}

Response

{
  "id": "12300000-0000-0000-0000-000000000000"
}

After this, you would start receiving https requests with a payload into the endpoint specified in Uri field. Description can be used for denoting the purpose of the webhook and is purely informational. EventType field indicates which event should be sent to the endpoint. So you can use a single endpoint for handling multitude of different events or specify a separate endpoint for each. Headers field is optional and it can be used to specify HTTP headers that should be sent to the endpoint.

The payload sent to the hook uri endpoint can be one of the following formats.

Signature request related events

{
  "EventType": "event type name",
  "Timestamp": "0001-01-01T00:00:00",
  "EventData": {
    "SignatureRequestId": "00000000-0000-0000-0000-000000000000",
    "TenantId": "00000000-0000-0000-0000-000000000000",
    "DepartmentId": "00000000-0000-0000-0000-000000000000",
    "CreatorId": "00000000-0000-0000-0000-000000000000"
  }
}

Signatory related events

{
  "EventType": "event type name",
  "Timestamp": "0001-01-01T00:00:00",
  "EventData": {
    "SignatoryId": "00000000-0000-0000-0000-000000000000",
    "SignatureRequestId": "00000000-0000-0000-0000-000000000000",
    "TenantId": "00000000-0000-0000-0000-000000000000",
    "DepartmentId": "00000000-0000-0000-0000-000000000000",
    "CreatorId": "00000000-0000-0000-0000-000000000000"
  }
}

Get all subscriptions

Request

GET https://api-dev.teliasign.com/hooks/v1/subscription
-H Authorization: Bearer {Retrieved authentication token.}
-H Ocp-Apim-Subscription-Key: {Subscription key which provides access to this API. Found in your Profile.}

Response

{
  "items": [
    {
      "id": "00000000-1111-2222-3333-444444444444",
      "eventType": "signaturerequeststatusupdated",
      "uri": "https://your-site.com/notifications",
      "description": "Your description"
    },
    {
      "id": "00000000-1111-2222-3333-555555555555",
      "eventType": "signaturerequestcompleted",
      "uri": "https://your-site.com/notifications",
      "description": "Your description"
    }
  ]
}

Get one particular subscription

Request

GET https://api-dev.teliasign.com/hooks/v1/subscription/{subscriptionId}?eventType={eventType}
-H Authorization: Bearer {Retrieved authentication token.}
-H Ocp-Apim-Subscription-Key: {Subscription key which provides access to this API. Found in your Profile.}

Response

{
  "id": "00000000-1111-2222-3333-444444444444",
  "eventType": "signaturerequeststatusupdated",
  "uri": "https://your-site.com/notifications",
  "description": "Your description"
}

Delete subscription

Request

DELETE https://api-dev.teliasign.com/hooks/v1/subscription/{subscriptionId}?eventType={eventType}
-H Authorization: Bearer {Retrieved authentication token.}
-H Ocp-Apim-Subscription-Key: {Subscription key which provides access to this API. Found in your Profile.}

Response

202 Accepted