Sync Webhook é o processo que envolve a comunicação LEX e Parceiro, onde a LEX envia dados automaticamente para outro sistema em tempo real ou próximo disso, sempre que ocorrem eventos específicos.
Definição de 🚀WEBHOOK
Atualmente temos dois modelos de hooks aceitos:
- USER_ACCESS
Esse evento representa o acesso de usuário a determinado produto (parceiro) e contem toda a estrutura da escola com o respectivo usuário.
- USER_ACCESS_REVOCATION
Esse evento representa a remoção do acesso do usuário a determinado produto (parceiro).
Receber Webhook é utilizado para processar eventos enviados. Ele recebe um payload JSON via uma requisição POST, que contém detalhes do evento e informações associadas. A autenticação é feita por meio de uma chave API (x-api-key), que deve ser incluída no cabeçalho da requisição para garantir que apenas clientes autorizados possam enviar dados ao sistema. O endpoint deve retornar uma confirmação de sucesso ou mensagens de erro dependendo da validade dos dados e da autenticação fornecida.
É importante que guardem o maximo de informações dos eventos enviados para fins de auditoria.
POST https://seu-dominio/api/v1/sua-rota-que-recebe-o-webhook
Este endpoint requer autenticação via x-api-key. O valor da chave deve ser incluído no cabeçalho da requisição.
| Nome |
Tipo |
Tamanho |
Descrição |
Content-Type |
string |
- |
Deve ser application/json |
x-api-key |
string |
1024 |
Chave de API utilizada para autenticação |
POST https://your-domain/api/v1/your-webhook-endpoint
Content-Type: application/json
x-api-key: 12345-abcde-67890-fghij
{
"example": "Your payload should go here"
}
curl \
--location 'https://seu-dominio/api/v1/sua-rota-que-recebe-o-webhook' \
--header 'Content-Type: application/json' \
--header 'x-api-key: ••••••' \
--data-raw '{ ...payload... }'
USER_ACCESS
{
"header": {
"request_id": "1234567890",
"client_id": "12345-abcde-67890-fghij",
"action": "USER_ACCESS",
"created_at": "2019-01-01T00:00:00Z"
},
"payload": {
"structure_school": {
"hash": "encrypt(tenant+school+class)",
"tenant": {
"hash": "encrypt(id+name+brand_name)",
"id": "12345-abcde-67890-fghij",
"name": "Grupo Econômico XPTO",
"external_id": "GT101",
"brand_name": "Marca"
},
"school": {
"hash": "encrypt(id+name+cpnj)",
"id": "12345-abcde-67890-fghij",
"name": "Escola teste",
"cpnj": "11.111.111\/0001-20",
"external_id": "ESCT1"
},
"class": {
"hash": "encrypt(id+name+school_id+course_code+educational_stage+grade+shift)",
"id": "12345-abcde-67890-fghij",
"name": "Turma XPTO",
"school_id": "12345-abcde-67890-fghij",
"code": "TU421123",
"external_id": "TU421",
"course_code": "C123",
"description": "Descrição da Turma XPTO",
"year": 2024,
"educational_stage": {
"id": "12345-abcde-67890-fghij",
"name": "EF"
},
"grade": {
"id": "12345-abcde-67890-fghij",
"name": "EF1"
},
"shift": {
"id": "12345-abcde-67890-fghij",
"name": "Integral"
}
}
},
"structure_users": {
"hash": "encrypt(users)",
"users": [
{
"hash": "encrypt(id+name+account_id+date_of_birth+email+documents+responsible_ids)",
"id": "12345-abcde-67890-fghij",
"account_id": "12345-abcde-67890-fghij",
"name": "FILHA XPTO",
"date_of_birth": "2020-01-01",
"cell_phone": {
"ddi": "+55",
"value": "5511999999999"
},
"email": "usuario@email.com",
"academic_email": "usuario@email.com",
"login": "filha_xpto",
"external_id": "FILHA_XPTO",
"documents": [
{
"type": "cpf",
"value": "11111111111"
}
],
"responsible_ids": [
"12345-abcde-67890-fghij"
]
},
{
"hash": "encrypt(id+name+account_id+date_of_birth+email+documents+responsible_ids)",
"id": "12345-abcde-67890-fghij",
"account_id": "12345-abcde-67890-fghij",
"name": "MAE FILHA XPTO",
"date_of_birth": "2020-01-01",
"cell_phone": {
"ddi": "+55",
"value": "5511999999999"
},
"email": "usuario@email.com",
"academic_email": "usuario@email.com",
"login": "MAEfilha_xpto",
"external_id": "MAEFILHA_XPTO",
"documents": [
{
"type": "cpf",
"value": "11111111111"
}
],
"responsible_ids": []
}
],
"bond": {
"user_id": "12345-abcde-67890-fghij",
"class_id": "12345-abcde-67890-fghij",
"profiles": [
{
"id": "12345-abcde-67890-fghij",
"name": "Student"
}
],
"subjects": [
{
"id": "12345-abcde-67890-fghij",
"name": "Math"
}
]
}
}
}
}
Header
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| request_id |
string |
36 |
✔ |
O identificador único da requisição. |
| client_id |
string |
200 |
✔ |
O identificador do client associado ao parceiro. |
| action |
string |
100 |
✔ |
A ação que foi disparada (webhook). |
| created_at |
datetime |
20 |
✔ |
Data de criação da requisição. |
Payload
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| structure_school |
StructureSchool |
|
✔ |
Estrutura da escola. |
| structure_users |
StructureUsers |
|
✔ |
Estrutura de usuários. |
StructureSchool
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| hash |
string |
500 |
✔ |
Junção das informações encriptadas para otimização de consultas. |
| tenant |
Tenant |
|
✔ |
Grupo econômico. |
| school |
School |
|
✔ |
Escola. |
| class |
Class |
|
✔ |
Turma. |
StructureUsers
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| hash |
string |
500 |
✔ |
Junção das informações encriptadas para otimização de consultas. |
| users |
User[] |
|
✔ |
Lista de usuários pois no caso do aluno pode possuir responsáveis. |
| bond |
Bond |
|
✔ |
Relacionamento do usuário com a turma. |
Tenant
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| hash |
string |
500 |
✔ |
Junção das informações encriptadas para otimização de consultas. |
| id |
string |
36 |
✔ |
O identificador único do grupo econômico sobre o qual você deseja recuperar informações. |
| name |
string |
100 |
✔ |
O nome oficial do grupo econômico. Pode ser o nome da rede de escolas, empresa ou outra organização. |
| external_id |
string |
50 |
|
Um identificador único do grupo econômico que pode ser utilizado em sistemas externos ou em outras integrações. |
| brand_name |
string |
50 |
✔ |
A marca ou nome comercial associado ao grupo econômico. |
School
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| hash |
string |
500 |
✔ |
Junção das informações encriptadas para otimização de consultas. |
| id |
string |
36 |
✔ |
O identificador único da escola. Esse ID é utilizado para referenciar a escola dentro do sistema. |
| name |
string |
50 |
✔ |
Nome da escola. |
| cnpj |
string |
18 |
✔ |
O CNPJ (Cadastro Nacional da Pessoa Jurídica) da escola. Esse é um documento de identificação fiscal da escola no Brasil. |
| external_id |
string |
50 |
|
Um identificador único da escola utilizado em sistemas externos ou integrações. |
CellPhone
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| ddi |
string |
5 |
✔ |
O codígo de discagem direta internacional. |
| value |
string |
20 |
✔ |
O número de telefone. |
Class
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| hash |
string |
500 |
✔ |
Junção das informações encriptadas para otimização de consultas. |
| id |
string |
36 |
✔ |
Id da turma. |
| name |
string |
100 |
✔ |
Nome da turma. |
| school_id |
string |
36 |
✔ |
Id da escola. |
| code |
string |
50 |
✔ |
Identificador da turma. |
| external_id |
string |
50 |
|
Um identificador único da turma que pode ser utilizado em sistemas externos ou em outras integrações. |
| course_code |
string |
50 |
|
Codígo do curso que contem na turma. |
| description |
string |
500 |
|
Descrição da turma. |
| year |
int |
4 |
✔ |
Ano letivo da turma. |
| educational_stage |
EducationalStage |
|
✔ |
Segmento da turma. |
| grade |
Grade |
|
✔ |
Seríe da turma. |
| shift |
Shift |
|
|
Turno da turma. |
EducationalStage
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| id |
string |
36 |
✔ |
Id do segmento. |
| name |
string |
80 |
✔ |
Nome do segmento. |
Grade
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| id |
string |
36 |
✔ |
Id da serie. |
| name |
string |
80 |
✔ |
Nome da serie. |
Shift
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| id |
string |
36 |
✔ |
Id do turno. |
| name |
string |
80 |
✔ |
Nome do turno. |
User
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| hash |
string |
500 |
✔ |
Junção das informações encriptadas para otimização de consultas. |
| id |
string |
36 |
✔ |
O identificador único do usuário dentro da escola. |
| account_id |
string |
36 |
✔ |
O identificador único da conta do usuário. |
| name |
string |
100 |
✔ |
Nome do usuário. |
| date_of_birth |
string |
10 |
✔ |
A data de nascimento do usuário. (Formato YYYY-MM-DD). |
| cell_phone |
CellPhone |
|
|
O número de telefone do usuário. |
| email |
string |
200 |
|
O endereço de e-mail do usuário. |
| academic_email |
string |
200 |
|
O endereço de e-mail acadêmico do usuário |
| login |
string |
50 |
|
Login utilizado pelo usuário para acessar o sistema LEX. |
| external_id |
string |
50 |
|
O identificador único do usuário em sistemas externos. |
| documents |
Document[] |
|
|
Uma lista de documentos associados. |
| responsible_ids |
string[] |
36 |
|
Uma lista de ids dos seus responsáveis. |
Document
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| type |
string |
20 |
✔ |
O tipo de documento (por exemplo, identidade, passaporte). |
| value |
string |
20 |
✔ |
O valor ou número do documento. |
Bond
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| user_id |
string |
36 |
✔ |
O identificador único do usuário dentro da escola. |
| class_id |
string |
36 |
✔ |
Id da turma. |
| profiles |
Profile[] |
|
✔ |
Lista de perfis que usuário possui na turma. |
| subjects |
Subject[] |
|
|
Lista de disciplinas que o usuário possui na turma. |
Profile
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| id |
string |
36 |
✔ |
O identificador único do tipo de perfil. |
| name |
string |
64 |
✔ |
Nome do perfil do usuário. |
Subject
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| id |
string |
36 |
✔ |
O identificador único da disciplina. |
| name |
string |
50 |
✔ |
Nome da disciplina. |
USER_ACCESS_REVOCATION
{
"header": {
"request_id": "12345-abcde-67890-fghij",
"client_id": "12345-abcde-67890-fghij",
"action": "USER_ACCESS_REVOCATION",
"created_at": "2019-01-01T00:00:00Z"
},
"payload": {
"bond": {
"user_id": "12345-abcde-67890-fghij",
"class_id": "12345-abcde-67890-fghij",
"profiles": [
{
"id": "12345-abcde-67890-fghij",
"name": "Student"
}
],
"subjects": [
{
"id": "12345-abcde-67890-fghij",
"name": "Math"
}
]
}
}
}
Header
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| request_id |
string |
36 |
✔ |
O identificador único da requisição. |
| client_id |
string |
200 |
✔ |
O identificador do client associado ao parceiro. |
| action |
string |
100 |
✔ |
A ação que foi disparada (webhook). |
| created_at |
datetime |
20 |
✔ |
Data de criação da requisição. |
Payload
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| bond |
Bond |
|
✔ |
Relacionamento do usuário com a turma. |
Bond
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| user_id |
string |
36 |
✔ |
O identificador único do usuário dentro da escola. |
| class_id |
string |
36 |
✔ |
Id da turma. |
| profiles |
Profile[] |
|
✔ |
Lista de perfis que usuário possui na turma. |
| subjects |
Subject[] |
|
|
Lista de disciplinas que o usuário possui na turma. |
Profile
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| id |
string |
36 |
✔ |
O identificador único do tipo de perfil do usuário. |
| name |
string |
64 |
✔ |
Nome do perfil do usuário. |
Subject
| Parâmetro |
Tipo |
Tamanho |
Obrigatório |
Descrição |
| id |
string |
36 |
✔ |
O identificador único da disciplina do usuário. |
| name |
string |
50 |
✔ |
Nome da disciplina. |
Descrição: Endpoint para consultar o evento enviado para o parceiro.
Utilize o request_id retornado em cada uma das requisições para consultar o evento enviado.
Endpoint:
- GET
/webhook/v1/webhooks/callback/{request_id}
Cabeçalho:
Content-Type: application/jsonAuthorization: Bearer {access_token}
Parâmetros da rota
| Parâmetro |
Tipo |
Obrigatório |
Tamanho |
Descrição |
request_id |
UUID |
Sim |
36 |
ID da requisição . |
Resposta
200 Ok
{
"payload": "{\"id\":\"534220a3-54ee-4dd3-b673"}",
"message": "{\"id\":\"534220a3-54ee-4dd3-b673"}",
"status": 200,
"sentAt": "2024-01-01T22:32:13",
"isSuccessful": true
}
Parâmetros da resposta
| Parâmetro |
Tipo |
Obrigatório |
Tamanho |
Descrição |
payload |
string |
- |
- |
Payload do evento enviado. |
message |
string |
- |
- |
Mensagem da resposta. |
status |
int |
- |
- |
Codigo de status da resposta. |
sentAt |
Datetime |
- |
- |
Data do envio do evento (YYYY-MM-DDTHH:mm:ss). |
isSuccessful |
bool |
- |
- |
Status da resposta. |
401 Unauthorized (Sem autorização, ausência de token ou token incorreto)
400 BadRequest (Requisição incorreta)
500 Internal Server Error (Erro não mapeado no servidor)