Saltar al contenido principal

IWebhookMessagesApi

Visão Geral​

A interface IWebhookMessagesApi é responsável pela criação e publicação de eventos no sistema de webhooks. Esta API permite enviar novos eventos que serão processados e distribuídos através do sistema de partições.

Endpoints Disponíveis​

📤 Publicação de Eventos​

CreateMessageAsync​

Cria e publica um novo evento no sistema de webhooks. O evento será automaticamente roteado para uma partição e processado de acordo com as configurações do sistema.

Assinatura​

Task CreateMessageAsync(
    [Body] PublishEventDto publishEventDto,
    CancellationToken cancellationToken = default
);

Parâmetros​

PublishEventDto​

public class PublishEventDto
{
    [JsonPropertyName("consumerId")]
    public string? ConsumerId { get; set; }        // ID do consumidor (opcional, pode ser auto-preenchido)
    
    [JsonPropertyName("eventType")]
    public string EventType { get; set; } = string.Empty;  // Tipo do evento (obrigatório)
    
    [JsonPropertyName("data")]
    public object Data { get; set; } = new();      // Payload do evento (obrigatório)
    
    [JsonPropertyName("correlationId")]
    public string? CorrelationId { get; set; }     // ID de correlação para rastreamento
    
    [JsonPropertyName("headers")]
    public Dictionary<string, string>? Headers { get; set; } // Headers customizados
}

Campos Obrigatórios​

  • EventType: Identificador do tipo de evento (ex: "UserCreated", "OrderProcessed")
  • Data: Payload/conteúdo do evento

Campos Opcionais​

  • ConsumerId: Identificador do sistema consumidor (geralmente preenchido automaticamente)
  • CorrelationId: ID para rastrear o evento através de diferentes sistemas
  • Headers: Metadados adicionais em formato chave-valor

Exemplos de Uso​

Exemplo Básico​

await messagesApi.CreateMessageAsync(new PublishEventDto
{
    EventType = "UserRegistered",
    Data = new
    {
        UserId = 12345,
        Email = "joao@exemplo.com",
        Name = "João Silva",
        RegisteredAt = DateTime.UtcNow
    }
});

Evento com Correlation ID​

var correlationId = Guid.NewGuid().ToString();

await messagesApi.CreateMessageAsync(new PublishEventDto
{
    EventType = "OrderCreated",
    Data = new
    {
        OrderId = 67890,
        CustomerId = 12345,
        TotalAmount = 299.99m,
        Items = new[]
        {
            new { ProductId = 1, Quantity = 2, Price = 149.99m }
        }
    },
    CorrelationId = correlationId
});

// Use o correlationId para rastrear este evento em outros sistemas
Console.WriteLine($"Evento publicado com ID de correlação: {correlationId}");

Evento com Headers Customizados​

await messagesApi.CreateMessageAsync(new PublishEventDto
{
    EventType = "PaymentProcessed",
    Data = new
    {
        PaymentId = "PAY_123456",
        Amount = 199.90m,
        Currency = "BRL",
        Status = "approved"
    },
    CorrelationId = "payment-batch-001",
    Headers = new Dictionary<string, string>
    {
        { "Source", "PaymentService" },
        { "Version", "2.1" },
        { "Priority", "high" },
        { "Environment", "production" }
    }
});

Evento com Dados Complexos​

await messagesApi.CreateMessageAsync(new PublishEventDto
{
    EventType = "CustomerProfileUpdated",
    Data = new
    {
        CustomerId = 12345,
        Changes = new
        {
            PersonalInfo = new
            {
                Name = new { Old = "João", New = "João Silva" },
                Phone = new { Old = "+5511999999999", New = "+5511888888888" }
            },
            Preferences = new
            {
                Newsletter = new { Old = false, New = true },
                Notifications = new { Old = "email", New = "sms" }
            }
        },
        UpdatedBy = "user-portal",
        UpdatedAt = DateTime.UtcNow,
        ChangeReason = "customer-request"
    },
    CorrelationId = $"profile-update-{DateTime.UtcNow:yyyyMMdd}-{12345}",
    Headers = new Dictionary<string, string>
    {
        { "Source", "CustomerPortal" },
        { "UpdateType", "partial" },
        { "RequiresApproval", "false" }
    }
});

Tipos de Eventos Sugeridos​

Eventos de Usuário​

// Registro de usuário
EventType = "UserRegistered"
EventType = "UserActivated"
EventType = "UserDeactivated"
EventType = "UserProfileUpdated"
EventType = "UserPasswordChanged"

Eventos de Pedidos​

// Ciclo de vida do pedido
EventType = "OrderCreated"
EventType = "OrderPaid"
EventType = "OrderShipped"
EventType = "OrderDelivered"
EventType = "OrderCancelled"
EventType = "OrderReturned"

Eventos de Pagamento​

// Transações financeiras
EventType = "PaymentInitiated"
EventType = "PaymentProcessed"
EventType = "PaymentFailed"
EventType = "PaymentRefunded"
EventType = "PaymentChargedBack"

Eventos de Sistema​

// Eventos técnicos
EventType = "SystemMaintenanceScheduled"
EventType = "BackupCompleted"
EventType = "ErrorOccurred"
EventType = "PerformanceAlert"

Padrões de Dados Recomendados​

Estrutura Base Recomendada​

var baseEventData = new
{
    // IDs principais
    Id = "unique-identifier",
    UserId = "user-123",
    
    // Timestamps
    OccurredAt = DateTime.UtcNow,
    
    // Versionamento
    Version = "1.0",
    
    // Dados específicos do evento
    EventData = new
    {
        // Campos específicos aqui
    },
    
    // Metadados
    Metadata = new
    {
        Source = "nome-do-sistema",
        Environment = "production",
        Region = "us-east-1"
    }
};

Exemplo de Versionamento​

// Versão 1.0 do evento
await messagesApi.CreateMessageAsync(new PublishEventDto
{
    EventType = "ProductCreated",
    Data = new
    {
        ProductId = 123,
        Name = "Smartphone XYZ",
        Price = 999.99m,
        Version = "1.0"
    }
});

// Versão 2.0 do evento (com campos adicionais)
await messagesApi.CreateMessageAsync(new PublishEventDto
{
    EventType = "ProductCreated",
    Data = new
    {
        ProductId = 123,
        Name = "Smartphone XYZ",
        Price = 999.99m,
        Currency = "BRL",  // Novo campo
        Category = "Electronics",  // Novo campo
        Version = "2.0"
    }
});

Status HTTP​

Respostas de Sucesso​

  • 200 OK: Evento criado e publicado com sucesso

Respostas de Erro​

  • 400 Bad Request:

    • EventType não informado
    • Dados inválidos ou malformados
    • Payload muito grande

  • 401 Unauthorized:

    • API Key não fornecida
    • API Key inválida

  • 422 Unprocessable Entity:

    • Dados válidos mas que não podem ser processados
    • EventType não suportado

  • 429 Too Many Requests:

    • Rate limit excedido

  • 500 Internal Server Error:

    • Erro interno do servidor
    • Falha na comunicação com o sistema de filas

Exemplo de Tratamento de Erros​

try
{
    await messagesApi.CreateMessageAsync(new PublishEventDto
    {
        EventType = "TestEvent",
        Data = new { Message = "Hello World" }
    });
    
    Console.WriteLine("Evento publicado com sucesso!");
}
catch (ApiException ex) when (ex.StatusCode == HttpStatusCode.BadRequest)
{
    Console.WriteLine($"Dados inválidos: {ex.Content}");
}
catch (ApiException ex) when (ex.StatusCode == HttpStatusCode.Unauthorized)
{
    Console.WriteLine("Chave de API inválida ou não fornecida");
}
catch (ApiException ex) when (ex.StatusCode == HttpStatusCode.TooManyRequests)
{
    Console.WriteLine("Muitas requisições. Aguarde antes de tentar novamente.");
}
catch (ApiException ex)
{
    Console.WriteLine($"Erro da API: {ex.StatusCode} - {ex.Content}");
}
catch (Exception ex)
{
    Console.WriteLine($"Erro inesperado: {ex.Message}");
}

Rate Limiting​

A API possui limites de taxa para prevenir abuso:

  • Limite por minuto: 1000 requisições por API Key
  • Limite por hora: 10.000 requisições por API Key
  • Limite diário: 100.000 requisições por API Key

Headers de Rate Limit​

A API retorna headers informativos sobre os limites:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Implementando Backoff​

public async Task PublishWithRetry(PublishEventDto eventDto, int maxRetries = 3)
{
    for (int attempt = 1; attempt <= maxRetries