Overview 

The purpose of this document is to define the request and response JSON for subscribing to webhooks in Aimbase. 

Webhook subscribe data is submitted to our API via HTTP POST. The API will accept JSON based on what content type is set in the Content-Type HTTP header. To submit JSON data set the Content-Type header to “application/json”. 

The Webhook subscribe API requires authentication so the HTTP POST will require a valid Authenticate message header with an API token. See the Aimbase Authentication Web Service Specification for more details on how to retrieve a valid API token. 

Possible response codes are: 

• 201 (Created). This response indicates that the webhook subscription was created.  
• 400 (Bad Request). Along with the 400 response, the body of the response will contain an error message describing why the request was a bad request.
• 500 (Internal Server Error). An unknown error occurred during the request. 

HTTP Endpoint:

https://{baseaddress}/api/Webhook 

Additional Methods

List all active webhook subscriptions:

GET https://{baseaddress}/api/Webhook 

Get the details of a single active webhook subscription: 

GET https://{baseaddress}/api/Webhook/{Uid}

Update the details of a single active webhook subscription:

PUT https://{baseaddress}/api/Webhook/{Uid}

Deactivate or unsubscribe from a webhook subscription:

DELETE https://{baseaddress}/api/Webhook/{Uid}

Authenticating Webhooks 

Every time a webhook is created a new secret is generated for it, unless the secret is provided. This value is returned in the initial create response and is included with the webhook data when the webhook subscription information is returned in the GET requests. The webhook’s secret can be used to verify the source of all incoming webhook posts.

Each incoming webhook post will contain an Authenticate header in this format:

Authenticate: Bearer timestamp="{timestamp}",nonce="{nonce}",signature="{signature},publickey={publickey}" 

timestamp (int): Number of seconds passed since January 1, 1970 UTC.

nonce (string): Randomly generated string with length 50.

signature (string): An HMAC-SHA256 of the authenticate header.

publickey (string): A UID identifying the webhook being received.

To validate the webhook signature:

1. Concatenate the timestamp, nonce, and publickey values (in that order).
2. Calculate an HMAC-SHA256 for the concatenated values using the webhook subscription's secret as the key.
3. Verify that the result of #2 matches the signature. This verifies that the sender used the correct secret.
4. (Optional) Can cache the nonce of the request and reject any requests with nonces already seen. This prevents replay attacks.
5. (Optional) Can reject requests that have a timestamp of too far in the past.

This will effectively validate that the source of the incoming data is in fact Aimbase. This does not secure the content of the post. Transport layer security should be used to secure the content of the post.

Below is the list of properties that are accepted in the POST body. 

Webhook Data Schema 

Sample POST (JSON) 

{ 
    "Uid": "809b4161-0a70-434f-a42f-140fb0dfeb3a", 
    "PostUrl":"https://www.example.com/SurveyResponse", 
    "ManufacturerCode":"MF01", 
    "WebhookTypeCode":"SurveyResponse",
    "IntegrationTypeCode": "sample",  
    "Secret": "D9y7LhiePMcRrbWKOMaqWe8edzrYRBSIGa8DBFBeuAMBRX93M5n3GRMrxKYViiR4Y1G5ln198zo", 
    "Data": { 
        "key1":"value1", 
        "key2":"value2" 
    } 
}

Sample Response (JSON) 

{ 
  "Uid": "809b4161-0a70-434f-a42f-140fb0dfeb3a", 
  "PostUrl": "https://www.example.com/SurveyResponse", 
  "ManufacturerCode": "MF01", 
  "WebhookTypeCode": "SurveyResponse", 
  "IntegrationTypeCode": "sample",
  "Secret": "D9y7LhiePMcRrbWKOMaqWe8edzrYRBSIGa8DBFBeuAMBRX93M5n3GRMrxKYViiR4Y1G5ln198zo", 
  "Data": { 
    "key1": "value1", 
    "key2": "value2" 
  } 
}

Sample Failed Responses (JSON) 

The error responses below were generated by submitting a Survey Response without the required field “PostUrl”. 

{ 
  "Message": "The PostUrl field is required." 
} 

The error response below was generated by submitting a request with an invalid WebhookTypeCode 

{ 
  "Message": "Could not find WebhookType with code: Survey" 
}