Criar Webhook

Metodo

POST https://oapi.ogmma.com.br/v1/webhooks

Conceituacao

Este endpoint permite criar um novo webhook para receber notificacoes em tempo real sobre eventos que ocorrem na plataforma. Ao criar um webhook, voce define a URL de destino, os eventos que deseja monitorar e o secret para verificacao de assinatura HMAC-SHA256.

A URL informada deve utilizar HTTPS obrigatoriamente. O webhook sera criado no estado ativo por padrao e comecara a receber eventos imediatamente.

Atributos

Header

Atributo	Tipo	Obrigatorio	Descricao
Authorization	string	Sim	Chave de autenticacao da API. Bearer {API_KEY}
Content-Type	string	Sim	Tipo do conteudo. application/json

Body

Atributo	Tipo	Obrigatorio	Descricao
name	string	Sim	Nome identificador do webhook. Min 3, max 100 caracteres.
url	string	Sim	URL de destino para envio dos eventos. Deve ser HTTPS.
events	string[]	Sim	Lista de eventos que o webhook deve receber. Valores aceitos: message.received, message.sent, message.delivered, message.read, conversation.created, conversation.closed, channel.connected, channel.disconnected, contact.created, contact.updated, bulk.completed, bulk.failed.
secret	string	Sim	Chave secreta para geracao da assinatura HMAC-SHA256. Min 16 caracteres.
active	boolean	Nao	Define se o webhook esta ativo. Padrao: true.
retryPolicy	object	Nao	Configuracao da politica de tentativas de reenvio.
retryPolicy.maxRetries	number	Nao	Numero maximo de tentativas apos falha. Padrao: 5. Max: 10.
retryPolicy.retryDelay	number	Nao	Intervalo em milissegundos entre tentativas. Padrao: 30000. Min: 5000, max: 300000.

Request

cURL

curl -X POST "https://oapi.ogmma.com.br/v1/webhooks" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Notificacoes de Mensagens",
    "url": "https://meuservidor.com.br/webhooks/ogmma",
    "events": [
      "message.received",
      "message.sent",
      "conversation.created"
    ],
    "secret": "minha_chave_secreta_segura_123",
    "active": true,
    "retryPolicy": {
      "maxRetries": 5,
      "retryDelay": 30000
    }
  }'

Node.js

const axios = require('axios');

const response = await axios.post(
  'https://oapi.ogmma.com.br/v1/webhooks',
  {
    name: 'Notificacoes de Mensagens',
    url: 'https://meuservidor.com.br/webhooks/ogmma',
    events: [
      'message.received',
      'message.sent',
      'conversation.created'
    ],
    secret: 'minha_chave_secreta_segura_123',
    active: true,
    retryPolicy: {
      maxRetries: 5,
      retryDelay: 30000
    }
  },
  {
    headers: {
      'Authorization': 'Bearer {API_KEY}',
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);

Python

import requests

response = requests.post(
    'https://oapi.ogmma.com.br/v1/webhooks',
    json={
        'name': 'Notificacoes de Mensagens',
        'url': 'https://meuservidor.com.br/webhooks/ogmma',
        'events': [
            'message.received',
            'message.sent',
            'conversation.created'
        ],
        'secret': 'minha_chave_secreta_segura_123',
        'active': True,
        'retryPolicy': {
            'maxRetries': 5,
            'retryDelay': 30000
        }
    },
    headers={
        'Authorization': 'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
)

print(response.json())

Response

201 - Webhook criado com sucesso

{
  "data": {
    "id": "665f1a2b3c4d5e6f7a8b9c0d",
    "name": "Notificacoes de Mensagens",
    "url": "https://meuservidor.com.br/webhooks/ogmma",
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "events": [
      "message.received",
      "message.sent",
      "conversation.created"
    ],
    "active": true,
    "createdAt": "2024-06-10T14:30:00.000Z"
  }
}

400 - Dados invalidos

{
  "error": "VALIDATION_ERROR",
  "message": "Dados de entrada invalidos",
  "details": [
    {
      "field": "url",
      "message": "A URL deve utilizar protocolo HTTPS"
    }
  ]
}

401 - Nao autorizado

{
  "error": "UNAUTHORIZED",
  "message": "Token de autenticacao invalido ou ausente"
}

429 - Limite de requisicoes excedido

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Limite de requisicoes excedido. Tente novamente em alguns instantes.",
  "retryAfter": 60
}

Dica

O campo secret nao e retornado nas respostas da API por seguranca. Armazene-o com seguranca no momento da criacao, pois voce precisara dele para verificar as assinaturas dos eventos recebidos.