ENDPOINTS

Webhooks

Receba notificações em tempo real no seu servidor quando eventos ocorrem no MeuPonto360. Cada entrega é assinada com HMAC-SHA256 para verificação de autenticidade.

Eventos disponíveis

Evento	Quando dispara
`time_entry.created`	Nova batida de ponto registrada
`employee.created`	Novo colaborador criado
`adjustment.approved`	Ajuste de ponto aprovado
`adjustment.rejected`	Ajuste de ponto rejeitado

Verificação de assinatura

Toda entrega inclui o header X-MeuPonto360-Signature com formato t={timestamp},v1={hmac}. Valide assim:

const crypto = require('crypto');

function verifyWebhook(secret, rawBody, signatureHeader) {
  // Extrai timestamp e assinatura do header
  const parts = Object.fromEntries(
    signatureHeader.split(',').map(p => p.split('='))
  );
  const timestamp = parts['t'];
  const receivedHmac = parts['v1'];

  // Monta o payload assinado: "t={timestamp}.{body}"
  const payload = `t=${timestamp}.${rawBody}`;

  // Calcula o HMAC esperado
  const expectedHmac = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  // Comparação segura (evita timing attacks)
  return crypto.timingSafeEqual(
    Buffer.from(receivedHmac),
    Buffer.from(expectedHmac)
  );
}

// Exemplo em Express
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-meuponto360-signature'];
  const isValid = verifyWebhook(process.env.WEBHOOK_SECRET, req.body, signature);

  if (!isValid) return res.status(401).json({ error: 'Invalid signature' });

  const event = JSON.parse(req.body);
  console.log('Event:', event.event, event.data);

  res.json({ received: true });
});

💡

Rejeite eventos com timestamp mais antigo que 5 minutos para proteger contra ataques de replay.

POST/v1/webhookswebhooks:write

Registra um novo endpoint para receber eventos. O secret retornado é exibido apenas uma vez.

Parâmetros do body

Campo	Tipo	Obrig.	Descrição
`url`	string (URL)	sim	URL HTTPS que receberá os eventos via POST.
`events`	string[]	sim	Lista de eventos para assinar (ver tabela acima).
`description`	string	não	Descrição opcional do webhook.

curl -X POST https://api.meuponto360.com/v1/webhooks \
  -H "x-api-key: mp360_sk_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meu-servidor.com/webhooks/ponto",
    "events": ["time_entry.created", "adjustment.approved"],
    "description": "Integração com ERP"
  }'

201 Created

{
  "id": "wh-uuid-...",
  "url": "https://meu-servidor.com/webhooks/ponto",
  "events": ["time_entry.created", "adjustment.approved"],
  "description": "Integração com ERP",
  "active": true,
  "secret": "whsec_a1b2c3d4e5f6...",
  "createdAt": "2026-04-13T12:00:00.000Z"
}

⚠️

O secret é retornado apenas na criação e ao rotacionar. Armazene-o com segurança — não é possível recuperá-lo depois.

GET/v1/webhookswebhooks:read

Lista todos os webhooks cadastrados. O secret não é retornado na listagem.

PATCH/v1/webhooks/:idwebhooks:write

Atualiza URL, eventos, status (ativo/inativo) ou descrição de um webhook.

Campo	Tipo	Obrig.	Descrição
`url`	string (URL)	não	Nova URL do endpoint.
`events`	string[]	não	Nova lista de eventos.
`active`	boolean	não	Ativar ou pausar o webhook.
`description`	string	não	Nova descrição.

DELETE/v1/webhooks/:idwebhooks:write

Remove o webhook. Retorna 204 No Content.

POST/v1/webhooks/:id/rotate-secretwebhooks:write

Gera um novo secret para o webhook. O secret anterior é invalidado imediatamente.

GET/v1/webhooks/:id/deliverieswebhooks:read

Retorna o histórico de entregas do webhook com status HTTP, corpo da resposta e duração.

200 OK

[
  {
    "id": "del-uuid",
    "event": "time_entry.created",
    "url": "https://meu-servidor.com/webhooks/ponto",
    "httpStatus": 200,
    "durationMs": 142,
    "success": true,
    "responseBody": "{"received":true}",
    "createdAt": "2026-04-13T12:05:00.000Z"
  }
]