> ## Documentation Index
> Fetch the complete documentation index at: https://docs.piposaude.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks
> Receba notificações de acompanhamento do status das movimentações via HTTP POST.
A plataforma envia notificações de acompanhamento do status de movimentações, como recebimento do pedido e conclusão da movimentação (se de inclusão, já contendo a numeração de carteirinha e a data de início de vigência; se de exclusão, já contendo a data fim da vigência do benefício).
Essas notificações são hoje enviadas via e-mail para os representantes de RH cadastrados na empresa. Com a API essa funcionalidade foi expandida para que essas notificações também possam ser enviadas para uma URL da empresa, previamente cadastrada. A Pipo faz uma requisição HTTP em modo **POST** com os dados da notificação no corpo da requisição, codificados em JSON.
## Dados para cadastro de URL de WebHook
O cadastro deve ser solicitado para seu **Gerente de Contas da Pipo**.
* **URL**: Endereço para o qual será feita uma requisição HTTP em modo POST com os dados da notificação no corpo da requisição, codificados em JSON. Essa URL precisa ser acessível pela internet.
* **Chave de autorização**: Token de autorização que será enviado no header `Authorization` da requisição, em modo `Basic` (codificado em base64, segundo a [especificação HTTP — RFC 7617](https://datatracker.ietf.org/doc/html/rfc7617#section-2)).
## Notificações enviadas
Todas as notificações são enviadas com **Método** `POST` e **Autorização** HTTP Basic, com token previamente combinado.
Enviada quando o pedido de inclusão é recebido. Identificada por `enrollment-type: inclusion` e `status: enrollment-created`.
```json theme={null}
{
"request-id": "995a305a-2656-4b8b-b1fa-b8face7c7d5b",
"request-date": "2025-08-13",
"enrollment-id": "e4ba9307-8d2d-44dd-98f4-453ceea15726",
"enrollment-type": "inclusion",
"status": "enrollment-created",
"primary-name": "Member Number Five",
"primary-tax-id": "12345678900",
"company-name": "ACME Labs",
"company-tax-id": "12345678000190",
"carrier-name": "Minha Operadora de Saúde",
"product-name": "Super Plano Saúde Premium",
"product-type": "Plano de Saúde",
"enrollment-member-type": "primary"
}
```
```json theme={null}
{
"request-id": "995a305a-2656-4b8b-b1fa-b8face7c7d5b",
"request-date": "2025-08-13",
"enrollment-id": "e4ba9307-8d2d-44dd-98f4-453ceea15726",
"enrollment-type": "inclusion",
"status": "enrollment-created",
"primary-name": "Member Number Five",
"primary-tax-id": "12345678900",
"company-name": "ACME Labs",
"company-tax-id": "12345678000190",
"carrier-name": "Minha Operadora de Saúde",
"product-name": "Super Plano Saúde Premium",
"product-type": "Plano de Saúde",
"enrollment-member-type": "family",
"dependents": [{
"dependent-name": "Member Number Five Jr.",
"dependent-tax-id": "98765432100"
}]
}
```
```json theme={null}
{
"request-id": "995a305a-2656-4b8b-b1fa-b8face7c7d5b",
"request-date": "2025-08-13",
"enrollment-id": "e4ba9307-8d2d-44dd-98f4-453ceea15726",
"enrollment-type": "inclusion",
"status": "enrollment-created",
"primary-name": "Member Number Five",
"primary-tax-id": "12345678900",
"company-name": "ACME Labs",
"company-tax-id": "12345678000190",
"carrier-name": "Minha Operadora de Saúde",
"product-name": "Super Plano Saúde Premium",
"product-type": "Plano de Saúde",
"enrollment-member-type": "dependent",
"ad-hoc-dependent?": true,
"dependent-name": "Member Number Five Jr.",
"dependent-tax-id": "98765432100"
}
```
Enviada quando o pedido de exclusão é recebido. Identificada por `enrollment-type: exclusion` e `status: enrollment-created`.
```json theme={null}
{
"request-id": "995a305a-2656-4b8b-b1fa-b8face7c7d5b",
"request-date": "2025-08-13",
"enrollment-id": "e4ba9307-8d2d-44dd-98f4-453ceea15726",
"enrollment-type": "exclusion",
"status": "enrollment-created",
"primary-name": "Member Number Five",
"primary-tax-id": "12345678900",
"company-name": "ACME Labs",
"company-tax-id": "12345678000190",
"carrier-name": "Minha Operadora de Saúde",
"product-name": "Super Plano Saúde Premium",
"product-type": "Plano de Saúde",
"enrollment-member-type": "primary",
"request-extension-plan": false,
"requested-end-date": "2025-10-31"
}
```
```json theme={null}
{
"request-id": "995a305a-2656-4b8b-b1fa-b8face7c7d5b",
"request-date": "2025-08-13",
"enrollment-id": "e4ba9307-8d2d-44dd-98f4-453ceea15726",
"enrollment-type": "exclusion",
"status": "enrollment-created",
"primary-name": "Member Number Five",
"primary-tax-id": "12345678900",
"company-name": "ACME Labs",
"company-tax-id": "12345678000190",
"carrier-name": "Minha Operadora de Saúde",
"product-name": "Super Plano Saúde Premium",
"product-type": "Plano de Saúde",
"enrollment-member-type": "family",
"request-extension-plan": false,
"requested-end-date": "2025-10-31",
"dependents": [{
"dependent-name": "Member Number Five Jr.",
"dependent-tax-id": "98765432100"
}]
}
```
```json theme={null}
{
"request-id": "995a305a-2656-4b8b-b1fa-b8face7c7d5b",
"request-date": "2025-08-13",
"enrollment-id": "e4ba9307-8d2d-44dd-98f4-453ceea15726",
"enrollment-type": "exclusion",
"status": "enrollment-created",
"primary-name": "Member Number Five",
"primary-tax-id": "12345678900",
"company-name": "ACME Labs",
"company-tax-id": "12345678000190",
"carrier-name": "Minha Operadora de Saúde",
"product-name": "Super Plano Saúde Premium",
"product-type": "Plano de Saúde",
"enrollment-member-type": "dependent",
"request-extension-plan": false,
"requested-end-date": "2025-10-31",
"dependent-name": "Member Number Five Jr.",
"dependent-tax-id": "98765432100"
}
```
Enviada quando a inclusão é concluída, já contendo a numeração de carteirinha (`id-card-number`) e a data de início de vigência (`start-date`). Identificada por `enrollment-type: inclusion` e `status: enrollment-completed`.
```json theme={null}
{
"request-id": "995a305a-2656-4b8b-b1fa-b8face7c7d5b",
"request-date": "2025-08-13",
"enrollment-id": "e4ba9307-8d2d-44dd-98f4-453ceea15726",
"enrollment-type": "inclusion",
"status": "enrollment-completed",
"primary-name": "Member Number Five",
"primary-tax-id": "12345678900",
"company-name": "ACME Labs",
"company-tax-id": "12345678000190",
"carrier-name": "Minha Operadora de Saúde",
"product-name": "Super Plano Saúde Premium",
"product-type": "Plano de Saúde",
"enrollment-member-type": "family",
"id-card-number": "54588888123456789",
"start-date": "2023-10-01"
}
```
```json theme={null}
{
"request-id": "995a305a-2656-4b8b-b1fa-b8face7c7d5b",
"request-date": "2025-08-13",
"enrollment-id": "e4ba9307-8d2d-44dd-98f4-453ceea15726",
"enrollment-type": "inclusion",
"status": "enrollment-completed",
"primary-name": "Member Number Five",
"primary-tax-id": "12345678900",
"company-name": "ACME Labs",
"company-tax-id": "12345678000190",
"carrier-name": "Minha Operadora de Saúde",
"product-name": "Super Plano Saúde Premium",
"product-type": "Plano de Saúde",
"enrollment-member-type": "family",
"id-card-number": "54588888123456789",
"start-date": "2023-10-01",
"dependents": [{
"dependent-name": "Member Number Five Jr.",
"dependent-tax-id": "98765432100",
"id-card-number": "54588888123456790",
"start-date": "2023-10-02"
}]
}
```
```json theme={null}
{
"request-id": "995a305a-2656-4b8b-b1fa-b8face7c7d5b",
"request-date": "2025-08-13",
"enrollment-id": "e4ba9307-8d2d-44dd-98f4-453ceea15726",
"enrollment-type": "inclusion",
"status": "enrollment-completed",
"primary-name": "Member Number Five",
"primary-tax-id": "12345678900",
"company-name": "ACME Labs",
"company-tax-id": "12345678000190",
"carrier-name": "Minha Operadora de Saúde",
"product-name": "Super Plano Saúde Premium",
"product-type": "Plano de Saúde",
"enrollment-member-type": "dependent",
"id-card-number": "54588888123456790",
"start-date": "2023-10-02",
"dependent-name": "Member Number Five Jr.",
"dependent-tax-id": "98765432100"
}
```
Enviada quando a exclusão é concluída, já contendo a data fim da vigência do benefício (`end-date`). Identificada por `enrollment-type: exclusion` e `status: enrollment-completed`.
```json theme={null}
{
"request-id": "995a305a-2656-4b8b-b1fa-b8face7c7d5b",
"request-date": "2025-08-13",
"enrollment-id": "e4ba9307-8d2d-44dd-98f4-453ceea15726",
"enrollment-type": "exclusion",
"status": "enrollment-completed",
"primary-name": "Member Number Five",
"primary-tax-id": "12345678900",
"company-name": "ACME Labs",
"company-tax-id": "12345678000190",
"carrier-name": "Minha Operadora de Saúde",
"product-name": "Super Plano Saúde Premium",
"product-type": "Plano de Saúde",
"enrollment-member-type": "primary",
"request-extension-plan": false,
"requested-end-date": "2025-10-31",
"end-date": "2025-11-03"
}
```
```json theme={null}
{
"request-id": "995a305a-2656-4b8b-b1fa-b8face7c7d5b",
"request-date": "2025-08-13",
"enrollment-id": "e4ba9307-8d2d-44dd-98f4-453ceea15726",
"enrollment-type": "exclusion",
"status": "enrollment-completed",
"primary-name": "Member Number Five",
"primary-tax-id": "12345678900",
"company-name": "ACME Labs",
"company-tax-id": "12345678000190",
"carrier-name": "Minha Operadora de Saúde",
"product-name": "Super Plano Saúde Premium",
"product-type": "Plano de Saúde",
"enrollment-member-type": "family",
"request-extension-plan": false,
"requested-end-date": "2025-10-31",
"end-date": "2025-11-03",
"dependents": [{
"dependent-name": "Member Number Five Jr.",
"dependent-tax-id": "98765432100",
"end-date": "2025-11-03"
}]
}
```
```json theme={null}
{
"request-id": "995a305a-2656-4b8b-b1fa-b8face7c7d5b",
"request-date": "2025-08-13",
"enrollment-id": "e4ba9307-8d2d-44dd-98f4-453ceea15726",
"enrollment-type": "exclusion",
"status": "enrollment-completed",
"primary-name": "Member Number Five",
"primary-tax-id": "12345678900",
"company-name": "ACME Labs",
"company-tax-id": "12345678000190",
"carrier-name": "Minha Operadora de Saúde",
"product-name": "Super Plano Saúde Premium",
"product-type": "Plano de Saúde",
"enrollment-member-type": "dependent",
"request-extension-plan": false,
"requested-end-date": "2025-10-31",
"end-date": "2025-11-03",
"dependent-name": "Member Number Five Jr.",
"dependent-tax-id": "98765432100"
}
```
## Campos do payload
| Campo | Descrição |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `request-id` | Identificador único da requisição da notificação. |
| `request-date` | Data da solicitação. |
| `enrollment-id` | Identificador único da movimentação. |
| `enrollment-type` | Tipo da movimentação: `inclusion` ou `exclusion`. |
| `status` | Status da movimentação: `enrollment-created` (solicitada) ou `enrollment-completed` (concluída). Ver [Webhook Status](/docs/referencia/data-types/enums#webhook-status). |
| `primary-name` | Nome do titular. |
| `primary-tax-id` | CPF do titular. |
| `company-name` | Nome da empresa. |
| `company-tax-id` | CNPJ da empresa. |
| `carrier-name` | Nome da operadora de saúde. |
| `product-name` | Nome do produto. |
| `product-type` | Tipo do produto, em português (ex.: `Plano de Saúde`). Note que é diferente do enum [`Product Types`](/docs/referencia/data-types/enums#product-types) usado pela API (ex.: `health-insurance`). |
| `enrollment-member-type` | Tipo do beneficiário da movimentação: `primary`, `family` ou `dependent`. |
| `dependents` | Lista de dependentes (movimentações do tipo `family`). Cada item contém `dependent-name`, `dependent-tax-id` e, quando concluída, `id-card-number`/`start-date` (inclusão) ou `end-date` (exclusão). |
| `dependent-name` | Nome do dependente (dependente avulso). |
| `dependent-tax-id` | CPF do dependente (dependente avulso). |
| `ad-hoc-dependent?` | Indica se o dependente é avulso. |
| `id-card-number` | Numeração de carteirinha (presente na inclusão concluída). |
| `start-date` | Data de início de vigência (presente na inclusão concluída). |
| `request-extension-plan` | Indica se foi solicitado plano de extensão (movimentações de exclusão). |
| `requested-end-date` | Data fim de vigência solicitada (movimentações de exclusão). |
| `end-date` | Data fim de vigência do benefício (presente na exclusão concluída). |