Skip to content

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. 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
-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": "One of the tenant's signature request has been completed. A SignatureRequestStatusUpdated event is also launched.",
    "payloadSchema": {
      "EventType": "string",
      "Timestamp": "date",
      "EventData": {
        "SignatureRequestId": "guid",
        "TenantId": "guid",
        "DepartmentId": "guid"
      }
    }
  },
  {
    "eventType": "signaturerequeststatusupdated",
    "description": "The status of the tenant's signature requests has changed.",
    "payloadSchema": {
      "EventType": "string",
      "Timestamp": "date",
      "EventData": {
        "SignatureRequestId": "guid",
        "TenantId": "guid",
        "DepartmentId": "guid"
      }
    }
  }
]

Subscribing to events

The example how to subscribe to SignatureRequestCompleted event.

Request

POST https://api-dev.teliasign.com/hooks/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"
  }
}

Signatory related events

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

Document related events

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

Get all subscribtions

Request

GET https://api-dev.teliasign.com/hooks/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/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/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