How to setup a webhook
Steps
1 Analyze your needs
To begin, you will have to analyze the information you will need. To help you, you can consult the online documentation. The different events we support are listed there and the structure of Events objects can be found here.
For example, if I need to know when a user is created through SCIM, I have to listen to the event dir_sync.user.provision.success.
2 Create a Webhook endpoint
If you want to test whether notifications are received correctly or not, create an HTTP webhook test
Once your needs have been analyzed, you can create a test
require 'sinatra'
require 'json'
post '/webhook' do
puts request.body.read
end
This example was created using the Sinatra library. Here, we create a /webhook route that will listen to HTTP POST requests.
3 Process received events
The previously created
Once events are sent by Cryptr our services wait for a response. If the response is a 2xx response, we assume that you have received the event and we will not try to send it again.
If, on the other hand, you send us a different answer, we will try to resend the events to you at certain time intervals. To learn more about the different responses that you can send us and their actions, you can consult our How to properly manage your webhooks page which deals with this subject.
{
"__domain__": "3-belges",
"__environment__": "sandbox",
"__type__": "Event",
"code": "dir_sync.user.update.success",
"data": {
"__type__": "DirectorySyncEvent",
"change": "update",
"directory_sync_id": "2cbd4ad8-1f3c-4ea0-84b6-691d4d469e57",
"provider": "okta",
"resource": {
"changes": {
"new_values": {
"address": {
"country": "FR",
"formatted": "12 rue des freres lumières\n68200 Mulhouse, France",
"locality": "Mulhouse",
"postal_code": "68200",
"region": "Alsace",
"street_address": "12 rue des freres lumières"
},
"phone_numbers": [
{
"default": false,
"phone_country_code": 33,
"phone_national_number": "345676543",
"primary": true,
"type": "mobile",
"value": "+33345676543"
},
{
"default": true,
"phone_country_code": 33,
"phone_national_number": "687435543",
"primary": true,
"type": "work",
"value": "+33687435543"
}
],
"profile": {
"family_name": "O'neil",
"given_name": "April",
"preferred_username": "April O'neil",
},
"updated_at": "2023-06-06T08:49:33"
},
"previous_values": {
"address": {
"country": null,
"formatted": "12 rue des freres lumières\nMulhouse",
"locality": "Mulhouse",
"postal_code": null,
"region": null,
"street_address": "12 rue des freres lumières"
},
"phone_numbers": [],
"profile": {
"family_name": null,
"given_name": "Aprils",
"preferred_username": "O'neil",
},
"updated_at": "2023-06-06T08:06:21"
}
},
"id": "b4702922-5868-4db8-bcd9-87ab40af50ed",
"type": "User"
}
},
"errors": null,
"params": {
"addresses": [
{
"country": "FR",
"locality": "Mulhouse",
"postalCode": "68200",
"region": "Alsace",
"streetAddress": "12 rue des freres lumières"
}
],
"phoneNumbers": [
{
"primary": true,
"type": "work",
"value": "+33345676543"
},
{
"primary": true,
"type": "mbile",
"value": "+33687435543"
}
],
"name": {
"familyName": "O'neil",
"givenName": "April"
},
"displayName": "April O'neil",
},
"issued_at": "2023-06-06T08:49:33.075265Z",
"webhook_id": "webhook_2QauvX3scYnpadurUTdjrd59QrE"
}
Response
To ensure that we receive your confirmation response in the shortest possible time, you must send a response as soon as possible. You must process the sending of the response first before doing any other processing.
Retries
All 3xx, 4xx and 5xx codes will be processed by Cryptr to send you an event again at different intervals which you can consult in our "How to properly manage your webhooks". If we don't get a response or if we don't get it in time, we'll assume your
4 Create a test webhook
To test webhooks you can create a test webhook in your sandbox environment. Here is an example curl request that will allow you to create a webhook quickly:
curl -X POST '${cryptr_service_url}/api/v2/webhooks' \
-d 'name=webhook-name' \
-d 'target_url=https://your_target_url.fr' \
-d 'event_codes[]=all'
This webhook will listen to all events. If you wish, you can change the event codes to listen to by changing the value of the event_codes key. To see a full list of the event_codes available you can consult our Events List page.
5 Test the correct reception of the events
Check that your webhook is working properly. Are the events well received?
Now that your Webhook is created, you can test an event corresponding to an event listened to by your Webhook. In the case of a Webhook that listen to Directory Sync event you can for example test the event dir_sync.user.provision.success.
To do this, we provide you with an endpoint to trigger the sending of false events. To find out more, see How to test a Webhook or our API documentation.
If you used the same
POST request that we sent to you in your terminal.6 Deploy your endpoints on your services
If testing is successful, deploy your webhook
Once the configuration is tested, you can repeat the previous steps on your production environment. It is possible to create several different webhooks listening to several different events but also to define different target
/scim-webhook and another that sends SSO events to an /sso-webhook.