Smart Webhooks
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:
- Create a webhook endpoint on your server
- Register the endpoint with your Dashboard’s Webhooks settings
Create webhook endpoint on your
server
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.
Verify Signature
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).
Comparing the signatures
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.
Register the endpoint with your
Dashboard’s Webhooks settings
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.
Retry logic
If your endpoint is down or unavailable SMART retries the webhook request 4 times in 10, 30,
60 and 180 minutes. 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.
Event types
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
|
Event object
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
Payload schema examples
USER_PROJECT_STATUS_CHANGED
USER_TENDER_STATUS_CHANGED
USER_PROJECT_ADDED
USER_TENDER_ADDED
USER_PROJECT_UPDATED
USER_TENDER_UPDATED
