Webhook

Os Webhooks da Pottencial são uma maneira eficaz de receber notificações em tempo real sobre eventos importantes que ocorrem em nossa plataforma. Esses eventos incluem, mas não se limitam a: emissão de uma apólice, cancelamento de uma apólice, renovação de uma apólice. Quando o evento ocorre, a Pottencial faz uma solicitação HTTP POST para a URL que você configurou para o webhook.

Para integrar seus sistemas com os Webhooks da Pottencial, siga estas etapas:

Premissas

Quando um evento relevante ocorre, a Pottencial envia um POST request para o URL que você especificou como seu endpoint de Webhook. Este request inclui um payload JSON com informações detalhadas sobre o evento. Seu sistema pode então processar essas informações conforme necessário.

Para o funcionamento correto dos webhooks, os requisitos abaixo devem ser cumpridos.

• 1 - Implementar do lado do parceiro, um endpoint protegido por criptografia HTTPS e autenticação via ApiKey ou OIDC (ClientCredentials)
• 2 - O endpoint implementado deverá possuir obrigatoriamente o request ajustado conforme payloads descritos nesta documentação
• 3 - O endpoint implementado deverá utilizar o verbo POST
• 4 - O endpoint deverá retornar os status codes parametrizados nesta documentação
• 5 - Faça testes rigorosos para garantir que seu sistema esteja recebendo e processando corretamente os eventos dos Webhooks
• 6 - Monitore regularmente o funcionamento de seus Webhooks e faça as atualizações necessárias conforme novos eventos são adicionados ou mudanças são feitas em eventos existentes

Criar Autenticação

Permite registrar as autenticações dos webhooks do parceiro.

Request

Url	https://api-sandbox.pottencial.com.br/webhook/v1/auths
Method	Post
Headers	client_id	Client ID da App
	access_token	Token de acesso gerado para a App
Body	AuthRequest

Exemplo da Request de criação da autenticação com ApiKey

{
    "type": "ApiKey",
    "url": "https://developer.pottencial.com.br/webhook",
    "responseFieldToken": "",
    "meta": {
        "X-API-KEY": "KnjGWfTopUmxmgoT4hZmRQ=="
    }
}

Exemplo da Request de criação da autenticação com OIDC

{
    "type": "OIDC",
    "url": "https://developer.pottencial.com.br/webhook",
    "responseFieldToken": "access_token",
    "meta": {
        "client_id": "pottencial",
        "client_secret": "4d78ccea-2f11-4edb-ab0d-1373ded799e3",
        "grant_type": "client_credentials",
        "scope": "pottencial"
    }
}

Response

Status	Descrição	Tipo
201	Autenticação cadastrada para o webhook	AuthResponse
400	Os dados da requisição estão inválidos	ErrorResult
401	Parceiro não autorizado a realizar a operação	ErrorResult
403	Parceiro não autorizado a realizar a operação	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial.	ErrorResult

Exemplo da Response de criação da autenticação com ApiKey

{
    "id": "4d78ccea-2f11-4edb-ab0d-1373ded799e3",
    "type": "ApiKey",
    "url": "https://developer.pottencial.com.br/webhook",
    "responseFieldToken": "",
    "meta": {
        "X-API-KEY": "KnjGWfTopUmxmgoT4hZmRQ=="
    }
}

Exemplo da Response de criação da autenticação com OIDC

{
    "id": "4d78ccea-2f11-4edb-ab0d-1373ded799e3",
    "type": "OIDC",
    "url": "https://developer.pottencial.com.br/webhook",
    "responseFieldToken": "access_token",
    "meta": {
        "client_id": "pottencial",
        "client_secret": "4d78ccea-2f11-4edb-ab0d-1373ded799e3",
        "grant_type": "client_credentials",
        "scope": "pottencial"
    }
}

Buscar Autenticação

Permite buscar a autenticação dos webhooks do parceiro.

Request

Url	https://api-sandbox.pottencial.com.br/webhook/v1/auths
Method	Get
Headers	client_id	Client ID da App
	access_token	Token de acesso gerado para a App

Response

Status	Descrição	Tipo
200	Lista de Autenticações registradas para os webhooks	Lista de AuthResponse
400	Os dados da requisição estão inválidos	ErrorResult
401	Parceiro não autorizado a realizar a operação	ErrorResult
403	Parceiro não autorizado a realizar a operação	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial	ErrorResult

Exemplo da Response de busca da autenticação com ApiKey

[
    {
        "id": "4d78ccea-2f11-4edb-ab0d-1373ded799e3",
        "type": "ApiKey",
        "url": "https://developer.pottencial.com.br/webhook",
        "responseFieldToken": "",
        "meta": {
            "X-API-KEY": "KnjGWfTopUmxmgoT4hZmRQ=="
        }
    }
]

Exemplo da Response de busca da autenticação com OIDC

[
    {
        "id": "4d78ccea-2f11-4edb-ab0d-1373ded799e3",
        "type": "OIDC",
        "url": "https://developer.pottencial.com.br/webhook",
        "responseFieldToken": "access_token",
        "meta": {
            "client_id": "pottencial",
            "client_secret": "4d78ccea-2f11-4edb-ab0d-1373ded799e3",
            "grant_type": "client_credentials",
            "scope": "pottencial"
        }
    }
]

Excluir Autenticação

Permite excluir a autenticação dos webhooks do parceiro.

Request

Url	https://api-sandbox.pottencial.com.br/webhook/v1/auths/{id}
Method	Delete
Query	id	ID único do registro de Autenticação

Response

Status	Descrição	Tipo
204	Registro excluído com sucesso
400	Os dados da requisição estão inválidos	ErrorResult
401	Parceiro não autorizado a realizar a operação	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial.	ErrorResult

Subscrever

Permite subscrever o webhook em um Evento emitido pela Pottencial.

Request

Url	https://api-sandbox.pottencial.com.br/webhook/v1/subscriptions
Method	Post
Headers	client_id	Client ID da App
	access_token	Token de acesso gerado para a App
Body	WebhookRequest

Exemplo

{
    "url": "https://developer.pottencial.com.br/webhook",
    "eventType": "policy_issued"
}

Response

Status	Descrição	Tipo
201	Webhook subscrito com sucesso	WebhookResponse
400	Os dados da requisição estão inválidos	ErrorResult
401	Parceiro não autorizado a realizar a operação	ErrorResult
403	Parceiro não autorizado a realizar a operação	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial	ErrorResult

Exemplo

{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://developer.pottencial.com.br/webhook",
    "eventType": "policy_issued"
}
    

Buscar Subscrições

Permite listar as subscrições dos webhooks em Eventos emitidos pela Pottencial.

Request

Url	https://api-sandbox.pottencial.com.br/webhook/v1/subscriptions
Method	Get
Headers	client_id	Client ID da App
	access_token	Token de acesso gerado para a App
Query	id	ID único do webhook
Query	eventType	Tipo de evento (WebhookType)

Response

Status	Descrição	Tipo
200	Lista de Subscrições dos webhooks	Lista de WebhookResponse
400	Os dados da requisição estão inválidos	ErrorResult
401	Parceiro não autorizado a realizar a operação	ErrorResult
403	Parceiro não autorizado a realizar a operação	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial	ErrorResult

Exemplo

[
    {
        "id": "98293ld-35fd-36gjs4-0k3j-dad8723nfsd48",
        "url": "https://developer.pottencial.com.br/webhookIssued",
        "eventType": "policy_issued"
    },
    {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "url": "https://developer.pottencial.com.br/webhookCancelled",
        "eventType": "policy_cancelled"
    }
]

Alterar Subscrição

Permite alterar a subscrição do webhook em um Evento emitido pela Pottencial.

Request

Url	https://api-sandbox.pottencial.com.br/webhook/v1/subscriptions/{id}
Method	Put
Query	id	ID único do registro de Autenticação.
Headers	client_id	Client ID da App
	access_token	Token de acesso gerado para a App
Body	WebhookRequest

Exemplo

{
    "url": "https://developer.pottencial.com.br/webhook" 
}

Response

Status	Descrição	Tipo
200	Subscrição do Webhook atualizada com sucesso	WebhookResponse
400	Os dados da requisição estão inválidos	ErrorResult
401	Parceiro não autorizado a realizar a operação	ErrorResult
403	Parceiro não autorizado a realizar a operação	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial	ErrorResult

Exemplo

{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://developer.pottencial.com.br/webhook",
    "eventType": "policy_issued"
}

Excluir Subscrição

Permite excluir a subscrição do webhook em um Evento emitido pela Pottencial.

Request

Url	https://api-sandbox.pottencial.com.br/webhook/v1/subscriptions/{id}
Method	Delete
Query	id	ID único do webhook

Response

Status	Descrição	Tipo
204	Registro excluído com sucesso
400	Os dados da requisição estão inválidos	ErrorResult
401	Parceiro não autorizado a realizar a operação	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial	ErrorResult

Buscar Eventos de Webhook

Permite listar eventos emitidos de webhook que não foram enviados ao parceiro.

Request

Url	https://api-sandbox.pottencial.com.br/webhook/v1/subscriptions/events
Method	Get
Headers	client_id	Client ID da App
	access_token	Token de acesso gerado para a App
Query	skip	número de páginas, iniciando em 0
Query	take	quantidade de elementos a serem retornados

Response

Será retornada na header a chave x-total-count indicando o número de elementos disponíveis para busca.

Status	Descrição	Tipo
200	Lista de Eventos de webhook emitidos e não enviados	Lista de WebhookEventResponse
400	Os dados da requisição estão inválidos	ErrorResult
401	Parceiro não autorizado a realizar a operação	ErrorResult
403	Parceiro não autorizado a realizar a operação	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial	ErrorResult

Exemplo

[
    {
        "id": "98293ld-35fd-36gjs4-0k3j-dad8723nfsd48",
        "requestUrl": "https://developer.pottencial.com.br/webhookIssued",
	"requestBody": "Objeto WebhookEvent serializado",
        "eventType": "policy_issued",
	"statusCode": "400",
	"errorMessage": "Erro ao tentar emitir o evento",
	"eventDate": "2024-09-04"
    },
    {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "url": "https://developer.pottencial.com.br/webhookCancelled",
	"requestBody": "Objeto WebhookEvent serializado",
        "eventType": "policy_cancelled",
	"statusCode": "500",
	"errorMessage": "Erro ao tentar emitir o evento",
	"eventDate": "2024-09-04"
    }
]

Reenviar evento de webhook

Permite reenviar eventos de webhook que foram emitidos mas não enviados ao parceiro.

Request

Url	https://api-sandbox.pottencial.com.br/webhook/v1/subscriptions/events/send
Method	Post
Headers	client_id	Client ID da App
	access_token	Token de acesso gerado para a App
Body	WebhookSendEventRequest

Exemplo

{
    "eventIds": [
		"8c409247-ad91-4031-bc4d-3b3e11ba1383",
		"3ac2de19-8214-4768-bf78-378803e0908b"
	],
}

Response

Status	Descrição	Tipo
202	Evento foi reenviado para processamento	WebhookSendEventResponse
400	Os dados da requisição estão inválidos	ErrorResult
401	Parceiro não autorizado a realizar a operação	ErrorResult
403	Parceiro não autorizado a realizar a operação	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial	ErrorResult
502	Bad Gateway. Houve um erro inesperado no processamento de reenvio de alguns dos eventos recebidos na requisição.	ErrorResult

Exemplo

{
    "isSuccess": true
}
    

Notificação de Evento

Permite receber notificações de eventos emitidos pela Pottencial.

Request feita pela Pottencial

Url	Url cadastrada no webhook do parceiro que receberá uma notificação para um determinado evento
Method	Post
Headers	X-API-KEY	Chave da Api fornecida pelo parceiro	Caso a autenticação esteja configurada como ApiKey
	Authentication	Bearer Token recebido pelo servidor de autenticação do Parceiro	Caso a autenticação esteja configurada como OIDC
	Demais headers configurados pelo parceiro
Body	WebhookEvent

Response esperada pela Pottencial

Status	Descrição	Tipo
200	Evento recebido com sucesso pela API do Parceiro
400	Url do Parceiro não encontrada, erro inesperado	ErrorResult
401	Pottencial não autorizada para realizar a operação na API do parceiro	ErrorResult
408	Timeout, erro de tempo esgotado	ErrorResult
500	Erro interno da API do Parceiro	ErrorResult
502	Erro interno da API do Parceiro	ErrorResult

Simular notificação

Permite simular notificações de eventos emitidos pela Pottencial.

Request

Url	https://api-sandbox.pottencial.com.br/webhook/v1/subscriptions/events/{product_key}/emulate
Method	Post
Query	product_key	Produto Pottencial Imobiliário : imobiliario Residencial : residencial Seguro Estrutural : estrutural Aluguel Fiança Locaticia : aluguel Riscos de Engenharia : riscos-engenharia Pottencial Riscos Nomeados : riscos-nomeados Riscos Empresariais : empresarial Fiança Locatícia - Integral - PF : aluguel-integral-pf Fiança Locatícia - Integral - PJ : aluguel-integral-pj Fiança Locatícia - Tradicional - PF : aluguel-tradicional-pf Fiança Locatícia - Tradicional - PJ : aluguel-tradicional-pj Fiança Locatícia - Essencial - PJ : aluguel-essencial-pj Seguro Fiança Locatícia - Tradicional - PJ : aluguel-tradicional-pj Seguro Fiança Locatícia - Integral - PF : seguro-aluguel-integral-pf Seguro Fiança Locatícia - Essencial - PF : aluguel-essencial-pf Riscos Diversos Máquinas e Equipamentos : maquinas-equipamentos Riscos Diversos Benfeitorias e Produtos Agropecuários : benfeitorias Riscos Diversos Penhor Rural : penhor-rural Garantia Licitante : garantia-bid Garantia Performance : garantia-performance Judicial Execução Fiscal : Judicial-execucao-fiscal Garantia de pagamentos : garantia-pagamento Construção, Fornecimento ou Prestação de Serviço + Manutenção Corretiva Público: construcao-fornecimento-servico Judicial Trabalhista : judicial-trabalhista Garantia Judicial Civel : Judicial-civel Garantia Estentida : garantia-estendida Garantia Estentida : garantia-adiantamento Garantia Privado Retenção : garantia-retencao Garantia Judicial Trabalhista : judicial-trabalhista Judicial Depósito Recursal Substituição : judicial-deposito-recursal-substituicao Judicial Trabalhista - Substituição : judicial-trabalhista-substituicao Vida : vida Término de Obras - CAVA : termino-obras-cava Término de Obras - Infraestrutura : termino-obras-infraestrutura Garantia de Término de Obras: termino-obras Término de Obras - Manutenção Corretiva: termino-obras-corretiva Término de Obras - Banco do Brasil: termino-obras-bb Garantia Financeira Pagamentos - FINEP: garantia-pagamento Garantia Financeira - FINEP: garantia-adiantamento Garantia de Compra e venda de Energia: garantia-compra-venda-energia Garantia Parcelamento Administrativo Fiscal: judicial-fiscal
Headers	client_id	Client ID da App
	access_token	Token de acesso gerado para a App
Body	WebhookEmulateRequest

Exemplo

{
    "eventType": "policy_issued" 
}

Response

Status	Descrição	Tipo
202	Simulação de webhook realizada com sucesso	WebhookEmulateResponse
400	Os dados da requisição estão inválidos	ErrorResult
401	Parceiro não autorizado a realizar a operação	ErrorResult
403	Parceiro não autorizado a realizar a operação	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial	ErrorResult

Exemplo

{
    "statusCode": 200,
    "responseBody": "success"
}

Dicionário

Dicionário dos objetos enviados e recebidos pela Pottencial.

AuthType

Tipo de autenticação

• ApiKey: Tipo de autenticação onde a chave é enviada no cabeçalho da requisição.
• OIDC: Tipo de autenticação onde é resgatado um "token" em um autenticador e enviado no cabeçalho da requisição como "Bearer".

AuthRequest

Objeto que representa a criação da autenticação do webhook.

Campo	Tipo	Regras	Descrição
type	string (AuthType)	Obrigatório	Tipo de autenticação
url	string	Obrigatório	Endereço de um recurso na internet
responseFieldToken	string	Somente leitura	Campo de retorno do "Bearer Token"
meta	object	Obrigatório	Dicionário de chaves e valores para serem adicionados na requisição

AuthResponse

Objeto que representa a busca de uma autenticação do webhook.

Campo	Tipo	Regras	Descrição
id	string	Somente leitura	Identificador da autenticação
role	string	Somente leitura	Papel do parceiro no webhook
type	string (AuthType)	Opcional	Tipo de autenticação
url	string	Somente leitura	Endereço de um recurso na internet
responseFieldToken	string	Somente leitura	Campo de retorno do "Bearer Token"
meta	object	Opcional	Dicionário de chaves e valores para serem adicionados na requisição

WebhookType

Tipo de evento do webhook

• policy_issued: Criação de Apólice ou Endosso.
• policy_cancelled: Cancelamento de Apólice ou Endosso.

WebhookRequest

Objeto que representa a criação de uma subscrição do webhook.

Campo	Tipo	Regras	Descrição
url	string	Obrigatório	Endereço de um recurso na internet
eventType	string (WebhookType)	Obrigatório	Tipo de evento subscrito

WebhookResponse

Objeto que representa a busca de uma subscrição do webhook.

Campo	Tipo	Regras	Descrição
id	string	Somente leitura	Identificação do registro
url	string	Somente leitura	Endereço de um recurso na internet
eventType	string (WebhookType)	Somente leitura	Tipo de evento subscrito

WebhookEventResponse

Objeto que representa a busca de um evento de webhook.

Campo	Tipo	Regras	Descrição
id	string	Somente leitura	Identificação do registro
requestUrl	string	Somente leitura	Endereço de um recurso na internet
requestBody	string	Somente leitura	Dados do evento emitido
eventType	string (WebhookType)	Somente leitura	Tipo de evento subscrito
statusCode	string	Somente leitura	Código de erro http
errorMessage	string	Somente leitura	Mensagem de erro ao tentar emitir o evento
eventDate	date	Somente leitura	Data de emissão do evento

WebhookSendEventRequest

Objeto que representa o corpo de requisição do reenvio de eventos de Webhook

Campo	Tipo	Regras	Descrição
eventIds	string	Somente leitura	Identificador dos eventos que não foram enviados ao parceiro

WebhookSendEventResponse

Objeto que representa a resposta ao reenvio de eventos de Webhook

Campo	Tipo	Regras	Descrição
isSuccess	boolean	Somente leitura	Identificador de sucesso ou falha na resposta da requisição

WebhookEvent

Objeto que representa a notificação de um evento pela Pottencial para a API (webhook) do Parceiro.

Campo	Tipo	Regras	Descrição
type	string (WebhookType)	Somente leitura	Tipo de evento subscrito
data	object (WebhookData)	Somente leitura	O objeto é alterado de acordo com o produto segurado

WebhookData

Objeto que representa a notificação de um evento pela Pottencial para a API (webhook) do Parceiro. O objeto é alterado de acordo com o produto segurado.

Produto	Tipo	link
Apólice Imobiliario	Object	Ver payload
Apólice Risco Engenharia	Object	Ver payload
Apólice Garantia Estendida	Object	Ver payload
Apólice Aluguel - Fiança Locatícia	Object	Ver payload
Apólice Residencial	Object	Ver payload
Apólice Riscos Empresariais	Object	Ver payload
Apólice Riscos Nomeados	Object	Ver payload
Apólice Garantia Depósito Recursal e Garantia Depósito Recursal Substituição	Object	Ver payload
Apólice Judicial Trabalhista	Object	Ver payload
Apólice Garantia do Licitante BID	Object	Ver payload
Apólice Garantia do Executante Performance	Object	Ver payload
Apólice Seguro Estrutural	Object	Ver payload
Apólice Riscos Diversos - Máquinas e Equipamentos	Object	Ver payload
Apólice Riscos Diversos - Penhor Rural	Object	Ver payload
Apólice Riscos Diversos - Benfeitorias	Object	Ver payload
Apólice Seguro de Vida	Object	Ver payload

WebhookEmulateRequest

Objeto que representa a simulação de uma notificação do webhook.

Campo	Tipo	Regras	Descrição
eventType	string (WebhookType)	Obrigatório	Tipo de evento subscrito

WebhookEmulateResponse

Objeto que representa o resultado da simulação de uma notificação do webhook.

Campo	Tipo	Regras	Descrição
statusCode	number	Somente leitura	Status da requisição HTTPS feita para o Webhook do parceiro
responseBody	string	Somente leitura	Corpo da resposta retornada pelo Webhook do parceiro

Resolução de erros

Código	Erro	Descrição	Solução
400	Bad Request	Invalid secret in Authorization header	O client_secret informado no header é inválido. Verifique se o client_secret informado é o mesmo da APP e se o header Authorization está sendo passado conforme especificado
401	Unauthorized	Could not find a required APP in the request, identified by HEADER client_id.	O client_id informado no header é inválido. Verifique se o client_id informado é o mesmo da APP e se o header Authorization está sendo passado conforme especificado
404	Not Found	Not Found	Provavelmente a URL sendo chamado não está correta. Verifique se está conforme especificado
415	Unsupported Media Type	Content type not supported	O header Content-Type não está sendo informado conforme esperado. O correto é application/json
429	Too Many Requests	Too Many Requests	O consumidor estourou o limite de requisições por tempo. Aguarde um pouco para tentar novas requisições.
500	Internal Server Error	Internal Server Error	Erro não esperado, algo está quebrado na API. Por favor aguarde ou entre em contato com o time de suporte.

ErrorResult

Representa um resultado de erro na chamada da plataforma.

Campo	Tipo	Regras	Descrição
errors	Lista de ErrorMessage	Somente leitura	Lista de erros da solicitação

ErrorMessage

Contém informações de um erro.

Campo	Tipo	Regras	Descrição
code	string	Somente leitura	Código de identificação do erro
message	string	Somente leitura	Descrição do erro

Suporte e Atendimento ao Parceiro

Se você tiver alguma dúvida ou encontrar problemas durante o processo de integração, nossa equipe de suporte está sempre pronta para ajudar. Entre em contato conosco através do nosso canal de suporte dedicado a APIs.

Atualizações e Notificações

Mantenha-se atualizado sobre quaisquer mudanças ou atualizações nos Webhooks da Pottencial lendo nossas notificações de atualizações e participando de nossos encontros semanais.

Esta documentação é uma referência abrangente e detalhada para todos os aspectos dos Webhooks da Pottencial. Comece sua integração agora mesmo e aproveite ao máximo os benefícios dos Webhooks da Pottencial!