Distribuição

Webhook

Um webhook é uma requisição <span data-slate-string="true">HTTP</span> enviada automaticamente quando um evento acontece. Isso permite que o próprio servidor notifique o cliente do evento em vez de o cliente perguntar repetidamente. No App de distribuição, webhooks são usados para notificar o cliente quando os mesmos recebem novas distribuições.

Para receber webhooks do App de distribuição é necessário disponibilizar um endpoint para receber os disparos, que são requisições <strong class="StyledLeaf___StyledSpan-sc-129cvv1-0 hSAwv slate-bold" data-slate-leaf="true"><span data-slate-string="true">POST</span></strong>

Todas requisições internas precisam ter a propriedade <strong class="StyledLeaf___StyledSpan-sc-129cvv1-0 hSAwv slate-bold" data-slate-leaf="true"><span data-slate-string="true">X-Oystr-Auth</span></strong> no <strong class="StyledLeaf___StyledSpan-sc-129cvv1-0 hSAwv slate-bold" data-slate-leaf="true"><span data-slate-string="true">headers</span></strong>, recebendo o token que pode ser adquirido nas configurações do painel do Console como chave de API.

Ao receber novas distribuições, os webhooks notificarão a url cadastrada com o seguinte corpo.

{
  "webhookId": "id",
  "entity": {
    "type": "user",
    "id": "id",
    "username": "username"
  },
  "lastUpdateAt": null,
  "lastViewedAt": null,
  "endpoints": {
    "result": "/webhook/:id/results",
    "callback": "/webhook/:id/callback"
  }
}

CAMPO	DESCRIÇÃO
webhookId	Id do webhook
entity	Dados internos
lastUpdateAt	Última notificação realizada
lastViewedAt	Última visualização de novas distribuições
endpoints	Endpoints de auxílio para visualização dos resultados

Ajuda

Para ter acesso às rotas da integração, é possível fazer uma requisição <span data-slate-string="true">GET</span> com final <span data-slate-string="true">/help</span>

GET: https://console4.oystr.com.br/api/v1/service/disthook/webhook/help

RESPOSTA

[
    {
        "method": "GET",
        "endpoint": "/webhook/help",
        "description": "Descrição de cada rota"
    },
    {
        "method": "GET",
        "endpoint": "/webhook/:id",
        "description": "Informações do webhook"
    },
    {
        "method": "POST",
        "endpoint": "/webhook/:id/results",
        "description": "Resultado do webhook e confirmação de visualização"
    },
    {
        "method": "GET",
        "endpoint": "/webhook/:id/callback",
        "description": "Verificação do webhook"
    },
    {
        "method": "GET",
        "endpoint": "/webhook",
        "description": "Busca de webhooks"
    },
    {
        "method": "POST",
        "endpoint": "/webhook",
        "description": "Criação de webhook"
    },
    {
        "method": "PUT",
        "endpoint": "/webhook/:id",
        "description": "Modificação de webhook"
    },
    {
        "method": "DELETE",
        "endpoint": "/webhook/:id",
        "description": "Remoção de webhook"
    }
]

Informações

Para ter acesso às informações de um webhook já cadastrado, é possível fazer uma requisição GET com final /:id. O retorno trará as seguintes informações:

{
  "id": "id",
  "carteiraId": null,
  "userId": "id",
  "needView": false,
  "needNotify": false,
  "lastStatusCode": null,
  "lastResponse": null,
  "lastUpdateAt": null,
  "lastViewedAt": null,
  "url": "url",
  "headers": "{}",
  "createdAt": "2024-01-04T19:06:40.870Z",
  "updatedAt": "2024-01-04T19:06:40.870Z",
  "deletedAt": null,
  "entity": {
    "type": "user",
    "id": "id",
    "username": "username"
  }
}

CAMPO	DESCRIÇÃO
id	Id do webhook
carteiraId	Id da carteira vinculada
userId	Id do usuário vinculado
needView	Booleano para a necessidade de visualização de novos dados
needNotify	Booleano para a necessidade de notificação no endpoint definido
lastStatusCode	Último statusCode da requisição de notificação feita
lastResponse	Última resposta da requisição de notificação feita
lastUpdateAt	Última notificação realizada
lastViewedAt	Última visualização de novas distribuições
url	Url POST de disparo de notificação
headers	Parâmetros para a url de disparo de notificação
createdAt	Data de criação do webhook
updatedAt	Data de atualização do webhook
deletedAt	Data de deleção do webhook
entity	Dados internos