Working with webhooks

You can retrieve the supported hooks for each service by issuing a GET request to corresponding /{serviceroot}/hooks. This will return you the list of supported webhook events.

Retrieving a list of supported hooks

After sending a request to the /hooks endpoint, you will receive in response an array containing the supported events. For the purpose of this example, we will use signaturerequestcompleted event. Listing contains information about the event, along with an example of the payload it provides.

Request

GET https://sigplat-stage-signature-app.azurewebsites.net/hooks?tenantid={tenantId}
Authorization: Bearer {RetrievedToken}

Response

[
  {
    "id": "signaturerequestcompleted",
    "description": "One of the tenant's signature request has been completed. A SignatureRequestStatusUpdated event is also launched.",
    "payloadSchema": "{
      \"TenantId\": \"48d2e2d0-6ea9-4a25-88b9-48556276296d\",
      \"Event\": \"SignatureRequestCompleted\",
      \"Timestamp\": \"2018-07-10T08:41:29.0149818+00:00\",
      \"EventData\": {
        \"$type\": \"Javerdel.Services.Signature.API.Contracts.Result.Events.SignatureRequestEventResult, Javerdel.Services.Signature.API.Contracts\",
        \"Id\": \"00000000-0000-0000-0000-000000000000\",
        \"Subject\": null,
        \"CreatorId\": \"00000000-0000-0000-0000-000000000000\",
        \"CreatorName\": null,
        \"TenantId\": \"00000000-0000-0000-0000-000000000000\",
        \"SigningAuthorityId\": \"00000000-0000-0000-0000-000000000000\",
        \"StatusCode\": 0,
        \"Status\": null,
        \"Language\": null,
        \"DepartmentId\": null,
        \"ExpirationDate\": \"0001-01-01T00:00:00\",
        \"CreationDate\": \"0001-01-01T00:00:00\",
        \"ModifiedDate\": \"0001-01-01T00:00:00\",
        \"SignatureRequestTypeId\": null
      }
    }",
    "payloadType": "Javerdel.Services.Signature.API.Contracts.Result.Events.SignatureRequestEventResult",
    "payloadDescription": "Common event details with details of the completed signature request in payload field 'EventData'",
    "filters": [
      "signaturerequestcompleted"
    ],
    "headers": null,
    "properties": null
  }
]

Subscribing to events

We will use subscribing to new SignatureRequestCompleted event as an example.

Request

PUT https://sigplat-stage-signature-app.azurewebsites.net/hooks/{hookid}/subscription?tenantid={tenantid}
Authorization: Bearer {RetrievedToken}

{
  "Description": "Notifications for completed signature requests",
  "WebHookUri": "https://eventsink.vincitsign.com/notifications",
  "Filters": ["SignatureRequestCompleted"],
  "Headers": {
        "client-id": "00000000-0000-0000-0000-000000000000",
        "client-secret": "-",
    }
}

After this, you would start receiving https requests with a payload into the endpoint specified in WebHookUri field. Description can be used for denoting the purpose of the webhook, and is purely informational. Filters field indicates which events 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 (see the class SignatureRequestEventResult) sent to the hook uri endpoint has the following format

{
    "id": "[id]",
    "subject": "[subject]",
    "creatorid": "[creatorid]",
    "creatorname": "[creatorname]",
    "tenantid": "[tenantid]",
    "signingauthorityid": "[signingauthorityid]",
    "statuscode": "[statuscode]",
    "status": "[status]",
    "language": "[language]",
    "departmentid": "[departmentid]",
    "expirationdate": "[expirationdate]",
    "creationdate": "[creationdate]",
    "modifieddate": "[modifieddate]",
    "signaturerequesttypeid": "[signaturerequesttypeid]"
}