Plugin Webhooks - Mapas Culturais

Plugin para notificações via webhook de eventos das entidades do Mapas Culturais.

Funcionalidades

• Notificações automáticas quando entidades são criadas, atualizadas ou removidas
• Suporte a múltiplos tipos de entidades (Agentes, Projetos, Espaços, Eventos, Oportunidades, Inscrições)
• Configuração flexível via variáveis de ambiente ou código
• Sistema de retry automático para falhas na entrega
• Validação de assinatura com chave secreta (opcional)
• Timeout configurável para requisições HTTP

Instalação

1. Copie a pasta Webhooks para src/plugins/
2. Ative o plugin no arquivo de configuração:

// Em config/config.php ou config.d/plugins.php
'plugins' => [
    'Webhooks' => [
        'enabled' => true,
        'url' => 'https://seu-endpoint.com/webhook'
    ]
]

Configuração

Variáveis de Ambiente

Configure as seguintes variáveis no arquivo .env:

# Habilitar/desabilitar webhooks
WEBHOOKS_ENABLED=true

# URL do endpoint que receberá os webhooks (obrigatório quando habilitado)
WEBHOOKS_URL=https://exemplo.com/webhook

# Eventos para notificar (separados por vírgula)
WEBHOOKS_EVENTS=created,updated

# Entidades para monitorar (separados por vírgula, use * para todas)
WEBHOOKS_ENTITIES=Agent,Project,Space,Event,Opportunity,Registration

# Timeout da requisição HTTP em segundos
WEBHOOKS_TIMEOUT=5

# Chave secreta para assinatura dos webhooks (opcional)
WEBHOOKS_SECRET=sua-chave-secreta

# Número máximo de tentativas de entrega
WEBHOOKS_MAX_ATTEMPTS=5

Configuração via Código

'plugins' => [
    'Webhooks' => [
        'enabled' => true,
        'url' => 'https://exemplo.com/webhook',
        'events' => ['created', 'updated', 'deleted'],
        'entities' => ['Agent', 'Project', 'Space'],
        'timeout' => 10,
        'secret' => 'minha-chave-secreta',
        'maxAttempts' => 3
    ]
]

Eventos Suportados

• created - Quando uma entidade é criada
• updated - Quando uma entidade é atualizada
• deleted - Quando uma entidade é removida

Entidades Suportadas

• Agent - Agentes culturais
• Project - Projetos
• Space - Espaços culturais
• Event - Eventos
• Opportunity - Oportunidades
• Registration - Inscrições
• * - Todas as entidades acima

Formato do Webhook

O webhook será enviado via POST com o seguinte payload JSON:

{
  "event": "created",
  "entityClass": "MapasCulturais\\Entities\\Agent",
  "entityId": 123,
  "controller": "agent",
  "timestamp": "2024-01-15T10:30:00Z",
  "uuid": "a1b2c3d4e5f6g7h8",
  "changes": null,
  "entity": {
    "id": 123,
    "name": "Nome do Agente",
    "type": 1,
    "status": 1
  }
}

Campos do Payload

• event - Tipo do evento (created, updated, deleted)
• entityClass - Classe completa da entidade
• entityId - ID da entidade
• controller - Nome do controller da entidade
• timestamp - Data/hora do evento em ISO 8601
• uuid - Identificador único do webhook
• changes - Array com os campos alterados (apenas para evento updated)
• entity - Dados da entidade

Validação de Assinatura

Se configurado com secret, o webhook incluirá um header de assinatura:

X-Webhook-Signature: sha256=hash_do_payload_com_sua_chave

Exemplo de Validação (PHP)

function validateWebhook($payload, $signature, $secret) {
    $expectedSignature = 'sha256=' . hash_hmac('sha256', $payload, $secret);
    return hash_equals($expectedSignature, $signature);
}

// Uso
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$secret = 'sua-chave-secreta';

if (validateWebhook($payload, $signature, $secret)) {
    // Webhook válido, processar dados
    $data = json_decode($payload, true);
} else {
    // Webhook inválido
    http_response_code(401);
}

Sistema de Retry

O plugin implementa um sistema de retry automático:

• Tentativas são feitas em caso de falha na entrega
• Número máximo de tentativas configurável via maxAttempts
• Intervalos exponenciais entre tentativas
• Webhooks são processados via sistema de jobs em background

Headers HTTP Enviados

Content-Type: application/json
X-Webhook-Event: created|updated|deleted
X-Webhook-Entity: Agent|Project|Space|Event|Opportunity|Registration
X-Webhook-ID: uuid-único-do-webhook
X-Webhook-Signature: sha256=hash (se secret configurado)
User-Agent: MapasCulturais-Webhook/1.0

Exemplo de Endpoint Receptor

<?php
// webhook-receiver.php

$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

// Validar assinatura (se usando secret)
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
if ($signature && !validateWebhook($payload, $signature, 'sua-chave')) {
    http_response_code(401);
    exit('Unauthorized');
}

// Processar evento
switch ($data['event']) {
    case 'created':
        // Entidade foi criada
        logEvent("Nova {$data['controller']} criada: {$data['entity']['name']}");
        break;

    case 'updated':
        // Entidade foi atualizada
        $changes = implode(', ', array_keys($data['changes'] ?? []));
        logEvent("Entidade {$data['entityId']} atualizada: {$changes}");
        break;

    case 'deleted':
        // Entidade foi removida
        logEvent("Entidade {$data['entityId']} removida");
        break;
}

// Responder com sucesso
http_response_code(200);
echo 'OK';

function logEvent($message) {
    error_log(date('Y-m-d H:i:s') . " - $message\n", 3, 'webhooks.log');
}

function validateWebhook($payload, $signature, $secret) {
    $expectedSignature = 'sha256=' . hash_hmac('sha256', $payload, $secret);
    return hash_equals($expectedSignature, $signature);
}
?>

Monitoramento e Debug

Logs

Os webhooks são processados via jobs em background. Para monitorar:

1. Verificar logs do sistema de jobs
2. Verificar status das tentativas na interface de administração
3. Monitorar resposta HTTP do seu endpoint

Testando Configuração

Use ferramentas como webhook.site para testar:

WEBHOOKS_URL=https://webhook.site/seu-uuid-aqui

Debug Mode

Para debug, você pode temporariamente modificar o código para logar informações:

// Em Plugin.php, método enqueueWebhook()
error_log('Enviando webhook: ' . json_encode($data));

Troubleshooting

Webhook não está sendo enviado

1. Verificar se WEBHOOKS_ENABLED=true
2. Verificar se WEBHOOKS_URL está configurada
3. Confirmar que a entidade está na lista WEBHOOKS_ENTITIES
4. Verificar se o evento está em WEBHOOKS_EVENTS

Falhas na entrega

1. Verificar conectividade com a URL de destino
2. Confirmar que o endpoint responde com status 200
3. Verificar timeout (WEBHOOKS_TIMEOUT)
4. Revisar logs do sistema de jobs

Payload inválido

1. Verificar configuração do secret em ambos os lados
2. Confirmar que o endpoint aceita Content-Type: application/json
3. Validar estrutura JSON esperada

Contribuição

Para contribuir com melhorias:

1. Fork do repositório
2. Criar branch para feature/bugfix
3. Implementar testes se necessário
4. Enviar Pull Request

Licença

Este plugin segue a licença AGPL.