Webhooks

Webhooks enable you to receive events from Signatu. When a certain event you are subscribed to, e.g., somebody consents to a a policy, Signatu will send a HTTP POST to the registered webhook url with event data. You can use the data to trigger actions in your systems - e.g., update

A webhook is associated with an Application, so all events for that Application is sent to that hook. You can have any number of webooks, e.g., if you want notifications to multiple systems.

Endpoint

NOTE: webhooks are used across multiple Signatu APIs. Hence you will register webhooks at https://api.signatu.com/webhooks/v0

Registering a webhook

You can register a webhook through the API using a valid Access Token. Since an access token is associated with a specific Application, the webhook will be registered for that Application.

To register a webhook for e.g., the consent event:

$ curl https://api.signatu.com/webhooks/v0 \
      -H 'Authorization: Bearer YOUR_OAUTH_TOKEN' \
      -H 'x-api-key: YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d  \
       '{\
          "url": "https://my.server/webhookhandler", \
          "events": ["consent"] \
       }'
{
  "appId": "f7e4475897b694eaf62c4ebe5bd5e032",
  "url": "https://my.server/webhookhandler",
  "events": [
    "consent"
  ],
  "id": 1
}

Custom headers

You can set headers in the webhook using the headers field. This can be useful to e.g., authorize the webhook access to your API. To set headers, simply include a headers map when registering the webhook:

$ curl https://api.signatu.com/webhooks/v0 \
      -H 'Authorization: Bearer YOUR_OAUTH_TOKEN' \
      -H 'x-api-key: YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d  \
       '{\
          "url": "https://my.server/webhookhandler", \
          "events": ["consent"] \
          "headers": {"Authorization": "MY_AUTH_DETAILS", "MyOtherHeader": "SOME_VALUE"}
       }'
{
  "appId": "f7e4475897b694eaf62c4ebe5bd5e032",
  "url": "https://my.server/webhookhandler",
  "events": [
    "consent"
  ],
  "headers": {
    "Authorization": "MY_AUTH_DETAILS",
    "MyOtherHeader": "SOME_VALUE"
  }
  "id": 2
}

Showing registered webhooks

$ curl https://api.signatu.com/webhooks/v0 \
      -H 'Authorization: Bearer YOUR_OAUTH_TOKEN' \
      -H 'x-api-key: YOUR_API_KEY' 
[
  {
  "url": "https://my.server/webhookhandler",
  "events": [
    "consent"
  ],
  "id": 1
}
]

Events

Events are sent to the webhook URL using POST with a JSON event payload. The event format contains two fields type and data. The type specifies the event type (see types below), and data is a JSON object representing the actual event data:

{
  "type": "consent",
  "text": "Some (optional) human-readable description of the event",
  "data": { ... }  
}

Example consent event

data contains the full consent event (see Fields for a complete description).

{
  "type": "consent",
  "text": "Subject 1666a664380aad0d6d4ed0cb3357be28637b3a25a18b9b3f1c49501e7835d73a just consented to https://signatu.com/api/v0/policies/5", 
  "data": {
    "subject": "1666a664380aad0d6d4ed0cb3357be28637b3a25a18b9b3f1c49501e7835d73a",
    "issuer": "https://signatu.com/api/v0/datacontrollers/23",
    "target": "https://signatu.com/api/v0/policies/5",
    "source": "https://signatu.com/app/tab/integrate",
    "action": true,
    "token": "TMCMB6",
    "createdAt": "2017-02-24T08:45:34.398Z"
  }
}