Webhook is a callback method in which one software system can instantly notify another of an event in real time.
Webhooks at Uspacy help to automate work in Space. Namely, to automatically "notify" third-party services about certain events that take place at Uspacy.
To work with webhooks, go to the Space page of the same name. Then, expand the Automation section.
That's why you can work with both outgoing and incoming webhooks at Uspacy.
All the work is done on the corresponding page. To access it, expand the Automation section.
🌟Please note that only the owner (super administrator) and administrator of the Space have access to this section.
⚙️ Since these actions require certain technical skills, we recommend the webhooks to be configured by specialist developers. Or you can always contact our partners for help.
Outgoing
How to create a new webhook?
To do this, click on the button on the Create button.
A window will open where you need to fill out all the fields. Select exactly what will happen and with which object to send data to third-party services based on these changes.
Event shows what exactly will happen. That is, the webhook will notify when the object has been created, changed, deleted, or the stage for it has been changed.
The event object is something the interaction takes place with. That is, the webhook will notify when an entity, namely a lead, deal, contact, company, activity, task, post, or comment, has been created, changed, deleted, or the stage has been changed for them.
❗️Please note that some entities are not compatible with some events. For example, you cannot create a webhook that will send stage change data for a contact, company, activity, etc. It is not possible because of the functionality of these entities.
Activity ensures the work of the webhook, after its confirmation.
Endpoint outside Uspacy - URL to send data to. The developer inserts a special code that will process incoming requests (messages).
💡This address must be valid and publicly accessible. In the field, specify it with https://. That is, https://MN.XY, where https:// is the protocol and MN.XY is the domain name.
When all fields are filled out, click Create.
The webhook will be added to the general list at once. Initially, it will receive a status of Unconfirmed. Therefore, in order for the webhook to start working correctly, it needs to be confirmed. ⬇️
How to confirm a webhook?
After creating the webhook, Uspacy will send a POST request to your endpoint URL with a confirmation link.
Your server has to accept that request, extract that link, and follow it.
Done ✅
After that, the webhook will receive the status Confirmed and will work.
Useful links and tips
You can use ready-made Amazon SNS handlers for different languages and frameworks to confirm and process incoming messages.
🔍 PHP/Laravel: https://github.com/nipwaayoni/laravel-aws-sns
🔍 Python/Django https://gist.github.com/gaqzi/d3cf5e73afb42e535376
An example of an event message
{
"topic": "Notifications",
"type": "comment",
"env": "prod",
"data": {
"entity": {
"author_id": 1,
"entity_type": "task",
"entity_id": 786,
"message": "<p class=\"PlaygroundEditorTheme__paragraph\" dir=\"ltr\"><span>test<\/span><\/p>",
"date": 1690963631,
"id": 9087,
"mentioned": {
"users": [],
"departments": [],
"groups": []
},
"notify": {
"users": [
1
],
"groups": [],
"departments": []
}
},
"user_id": 1,
"service": "comments",
"domain": "my.uspacy.ua",
"timestamp": "2023-08-02T08:07:11.256570Z",
"action": "create"
},
"metadata": []
}
Incoming
How to create a new incoming webhook?
To do this, click on the corresponding button.
A window will open where you need to fill out all the fields. They are:
Name – helps identify the newly created webhook among others. It can be arbitrary and should provide a brief description of what will happen.
Access – the tool(s) of Space that the webhook will have access to. Uspacy will accept data within these services (CRM, Tasks, Chats, Activities, etc.) and perform certain actions based on the predefined logic.
Activity – ensures the webhook works immediately after it is created.
Once all fields are filled out, click Create.
The webhook will be added to the general list at once. It will get an Activated status and will be ready for use.
When opening it, you will see a new field: Webhook address.
How to use incoming webhooks?
After creating an incoming webhook and granting it access to the necessary tools, you can use the Uspacy REST API for your Space without the need for token-based authorization.
Additionally, as we already know, once an incoming webhook is created, the system automatically generates a unique URL for it.
This URL is used to form the API request.
🟣 For example, access was granted to the Tasks tool.
Then the specific task can be received by using the following URL:
{webhook_url}/tasks/v1/tasks/{task_id}
Where:
{webhook_url}is the URL copied from the webhook settings window./tasks/v1/tasks/{task_id}is the relative path to the endpoint of the corresponding service (tool) that the webhook has access to. You can find this path in the API documentation.
🔍 Description of the corresponding method in the API documentation.
Example of an API request:
Response:
{
"id": "816",
"parentId": 250,
"title": "Task",
"setterId": "1",
"createdBy": "1",
"createdDate": 1732623300,
"departmentId": "1",
"groupId": "2",
"closedBy": "",
"responsibleId": "2",
"deadline": 0,
"closedDate": null,
"body": "<p class=\"PlaygroundEditorTheme__paragraph\" dir=\"ltr\"><span style=\"white-space: pre-wrap;\">опис</span></p><p class=\"PlaygroundEditorTheme__paragraph\" dir=\"ltr\"><span style=\"white-space: pre-wrap;\">Description</span></p>",
"status": "notScheduled",
"priority": "veryHigh",
"resultCommentId": "",
"requiredResult": false,
"acceptResult": true,
"timeTracking": true,
"timeEstimate": 0,
"template": false,
"templateId": 294,
"delegation": true,
"basicTask": false,
"taskType": "task",
"accomplicesIds": [
"2",
"3",
"4",
"36",
"37",
"43",
"44",
"45",
"46",
"47"
],
"auditorsIds": [
"2",
"3",
"4",
"36",
"37",
"43",
"44",
"45",
"46",
"47"
],
"kanbanStageId": "",
"elapsedTimes": {
"totalSeconds": 0,
"myTime": 0,
"elapsedTimes": []
},
"crmEntities": {
"deals": [
{
"id": 124,
"title": "Deal"
}
],
"companies": [
{
"id": 39,
"title": "Company"
}
],
"universal_entity": [
{
"id": 2,
"title": "Universal"
}
]
},
"scheduler": {
"taskId": 294,
"active": true,
"nextRun": 1732709700,
"dateStart": "09.10.2024",
"hourStart": 54900,
"dateStop": null,
"timezoneOffset": 3,
"deadlineDay": null,
"deadlineHour": null,
"currentIteration": null,
"iteration": null,
"period": "day",
"every": 1,
"dayOfWeek": null,
"dayOfMonth": null,
"weekOfMonth": null,
"stoppedByForce": 0,
"createdAt": 1728475564,
"updatedAt": 1728475564
}
}
🟣 If access to CRM is selected in the settings for the incoming webhook.
Then you will be able to interact with all CRM entities in your Space via the API.
For example, a request to create a lead would look like this:
{webhook_url}/crm/v1/entities/{entity}
Where:
{webhook_url}is the URL copied from the webhook settings window./crm/v1/entities/{entity}is the relative path to the endpoint of the corresponding service (tool) that the webhook has access to. You can find this path in the API documentation.
🔍 Description of the corresponding method in the API documentation.
Example of an API request:
Request body:
{
"owner": 390,
"title": "Lead",
"comments": "qwerty"
}
Response:
{
"id": 414,
"created_at": 1732627155,
"updated_at": 1732627155,
"title": "Lead",
"owner": 390,
"created_by": 1,
"changed_by": "",
"converted": false,
"contacts": "",
"companies": "",
"first_name": "",
"last_name": "",
"patronymic": "",
"company_name": "",
"position": "",
"utm_source": "",
"utm_medium": "",
"utm_campaign": "",
"utm_content": "",
"utm_term": "",
"messengers": "",
"phone": "",
"email": "",
"comments": "qwerty",
"source": "",
"lead_label": "",
"kanban_status": "IN_WORK",
"kanban_reason_id": "",
"closed_by": "",
"closed_at": "",
"first_closed_by": "",
"first_closed_at": "",
"kanban_stage_id": 1,
"table_name": "leads",
"new_kanban_stage_id": null,
"old_kanban_stage_id": null
}
Note that in the case of CRM, access also depends on the user's permissions in the Space. This means you must have the appropriate permissions, such as the ability to create leads. Additionally, the webhook settings must grant access to the necessary tool, in this case, the CRM.
Example of an API request when the user does not have the required permissions:
Response:
{
"errors": {
"text": [
"Access is denied!"
]
},
"status": true
}
If you have additional questions or you need to contact the support, send a request to this email [email protected]