Smart uses webhooks to notify client’s application when an event happens in client’s account.
There are two steps to start using Smart webhooks:
A webhook is an endpoint on your server that receives requests from Smart, notifying you about events that happen on your account such as a user has received a project by trigger-filter. Add a new endpoint to your server and make sure it's publicly accessible so we can send unauthenticated POST requests.
Smart sends the event data in the request body. Each event is structured as an Event object with a event_type and related Smart resource nested under data.
As soon as you have the event object, check the type to know what kind of event happened. You can use one webhook to handle several different event types at once, or set up individual endpoints for specific events.
To acknowledge receipt of an event, your endpoint must return a 2xx HTTP status code to Smart. All response codes outside this range, including 3xx codes, indicate to Smart that you did not receive the event.
Send a successful 200 response to Smart as quickly as possible because Smart retries the event if a response isn't sent within a reasonable time. Write any long-running processes as code that can run asynchronously outside the webhook endpoint.
Smart signs the webhook events by including a signature in each event’s X-SMART-SIGNATURE header. This allows you to verify that the events were sent by Smart, not by a third party.
Before you can verify signatures, you need to retrieve your endpoint’s secret from your Dashboard’s Webhooks settings. Smart generates a unique secret key for each endpoint.
Smart generates signatures using a hash-based message authentication code (HMAC) with SHA-256 (base64 encoded).
Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the serialized request body payload as the message.
Compare the signature in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance (to protect against replay attack)
How to verify webhook signature? Step-by-step instruction
In order to verify the signature, you need to sign the body of the webhook on your side in exactly the same way as it was done when sending the webhook and then compare these signatures.
To do this, let's define the initial concepts:
Webhook secret key — is a constant value for each webhook, which you can get on the API settings / My webhooks —> View page. You should store this value on your side as a constant or environment variable. This value is Base64 encoded.
Webhook payload — is a JSON object that is sent each time the webhook fires as a body of the request.
SHA256 hash — is an algorithm for obtaining a hash-based message authentication code (HMAC). You need to find and include a library that implements this algorithm in accordance with your programming language.
Signature — is a unique value for each webhook payload that is calculated according to the SHA256 algorithm and transmitted in the webhook header 'x-smart-signature'. The signature is also Base64 encoded.
So, the process of verifying the signature of each webhook payload is as follows. (May differ depending on the library used!)
1. Decode the webhook secret key as Base64. Thus, we get the webhook secret key as a sequence of bytes.
2. Convert the payload into a sequence of bytes. You may need to specify the charset as UTF-8. (Depending on the programming language and the library used, it may not be necessary to convert the payload into a sequence of bytes).
3. Use the received on the first and second steps as parameters of the function of getting SHA256 hash; thus, we get the signature as a sequence of bytes.
4. Encode the signature obtained in step 3 as Base64.
5. Validate the signature that was got in step 4 by comparing it with the value of the 'x-smart-signature' header. If they are equal, the webhook is valid and verified. Otherwise, it should be ignored.
In your Dashboard’s Webhooks settings you can create, edit, activate/deactivate, unblock and delete endpoints.
Endpoint form contains the fields:
Endpoint URL
Required. The url of your endpoint
Webhook Version
Required. Selectable version of Smart webhook
Events to send
Required. You can attach all the available events to one endpoint, or you can separate them. It depends on architecture of you application.
Blocked Notification Email
Required. Email address which will be used to notify you if an endpoint has not responded with a 2xx HTTP status code for multiple hours in a row
Description
Optional.
Once you register the endpoint, the secret key will be generated. When you are ready, just activate the endpoint to start receiving events from Smart.
If your endpoint is down or unavailable and returns an HTTP status code of 500, 502, 503, 504, or 408, SMART will retry the webhook request up to 4 times at intervals of 10, 30, 60, and 180 minutes. If your endpoint returns a HTTP status code outside the expected HTTP range, the webhook is marked as 'Failed' without any retries. The total time from the first failed request until the webhook is blocked can be 4 hours 40 minutes if the endpoint’s functionality has not been restored. All this time, the webhook request has the 'Queuing' status, and after the last unsuccessful attempt the status changes to 'Failed'.
You can see the request status and other detailed information about retries on the 'API settings / My Webhook queue' page.
If all the retries fail, SMART blocks the endpoint and notifies you about this via 'Blocked Notification Email'. You can unblock it in your Dashboard’s Webhooks settings.
If your endpoint has been disabled or deleted when we attempt a retry, future retries of that event will be prevented. However, if you disable and then re-enable a webhook endpoint before we’re able to retry, you should still expect to see future retry attempts.
The list of event types:
| event_type | Description |
|---|---|
| USER_PROJECT_STATUS_CHANGED | User has changed the status of project |
| USER_TENDER_STATUS_CHANGED | User has changed the status of tender |
| USER_PROJECT_ADDED | The project has been added by trigger-filter to My Projects with NEW status |
| USER_TENDER_ADDED | The tender has been added by trigger-filter to My Tenders with NEW status |
| USER_PROJECT_UPDATED | The project in My Projects with WORKING WITH or MONITORING status has been updated |
| USER_TENDER_UPDATED | The tender in My Tenders with WORKING WITH or MONITORING status has been updated |
| USER_COMPANY_DEACTIVATION | The company in My Companies has been deactivated or reactivated
Important notes:
|
| USER_CONTACT_DEACTIVATION | The contact in My Contacts has been deactivated or reactivated
Important notes:
|
Event object (payload) contains meta fields and the related Smart information in data
Meta fields
event_type - the key of event type
version - the version of Smart webhook
message_id - unique identifier for the message, can be used to idempotence control
timestamp - the time when the event is sent to your endpoint
Event fields (data object)
user_id - user id connected to event
project_id / tender_id - entity id connected to event
user_project_status_id / user_tender_status_id - status id connected to event
datetime - datetime when the event was fired in Smart
activation_event_id - the event id related to entity activation & deactivation. New lookup company_activation_events / contact_activation_events is available to get the value.
replaced_with_id - the reference id of the company or contact it has been merged into