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]" }