Criar um webhook
Cadastre um destino para receber os eventos selecionados da sua empresa.
Cadastre uma URL de recebimento e selecione os eventos que sua integração
precisa acompanhar. Guarde o segredo retornado em um ambiente privado da
aplicação: as consultas de configuração não retornam esse valor. Se o
receptor ainda não estiver pronto, cadastre com is_active: false.
Veja Cadastrar o destino e Receber e validar eventos antes de iniciar o recebimento.
Cabeçalhos
Chave única escolhida pelo seu sistema para identificar esta requisição. Ao repetir a tentativa, envie a mesma chave e os mesmos parâmetros. Sem este header, a requisição é processada normalmente. Consulte o guia de idempotência para os prazos e o tratamento de respostas pendentes ou incertas.
1 a 255 caracteres
Parâmetros do corpo
Usar exemplo substitui os campos do corpo.
Nome para identificar o destino.
1 a 25 caracteres
URL HTTPS que recebe os eventos. Use a porta padrão 443 e um endereço público externo à Raims.
1 a 512 caracteres
Códigos dos eventos que este destino deve receber. Consulte o catálogo de eventos disponíveis.
Define se o destino pode receber eventos após o cadastro.
Respostas
Corpo da resposta
Webhook cadastrado. Guarde o segredo de assinatura retornado.
Webhook cadastrado e segredo necessário para validar suas assinaturas.
Identificador público do webhook.
Nome usado para identificar o destino.
URL HTTPS cadastrada para receber os eventos.
Códigos dos eventos assinados por este destino.
Indica se o webhook está ativo para receber eventos.
Motivo da desativação: manual para uma ação do cliente; continuous_failure pode aparecer em cadastros desativados anteriormente por falhas. Retorna null quando o webhook está ativo.
Instante da desativação, em segundos Unix UTC, ou null quando o webhook está ativo ou essa data não foi registrada.
Fim da validade do segredo anterior, em segundos Unix UTC, ou null quando não há transição vigente.
Instante do cadastro, em segundos Unix UTC.
Instante da última alteração do cadastro, em segundos Unix UTC.
Segredo usado para validar a assinatura dos eventos. Guarde-o em local seguro; as consultas do cadastro não o retornam.
Indica se os envios aguardam a retomada. O prazo original das entregas continua correndo durante a pausa.
Início da pausa atual, em segundos Unix UTC, ou null quando os envios não estão pausados.
Corpo da resposta
Um campo, filtro ou identificador está inválido. Confira os detalhes antes de repetir a requisição.
Código e explicação do erro retornado pela API.
Código estável do erro.
Explicação do erro em inglês. Em validações, resume a categoria; os detalhes identificam as correções. Use os códigos para tratar a resposta.
Falhas em campos recebidos ou referências enviadas no corpo, com campo, código e explicação. Omitido em erros gerais e quando não há correção de campo a indicar.
Nome público do campo JSON, parâmetro de consulta, parâmetro de rota ou header relacionado ao erro. Campos aninhados e listas preservam o caminho e o índice. $ representa a raiz do corpo JSON.
Motivo do erro no campo, como REQUIRED, INVALID_TAXID, UNKNOWN_FIELD, DUPLICATE_FIELD ou INVALID_TYPE.
Explicação em inglês sobre o problema nesse campo ou parâmetro e a correção disponível. Não use o texto para decidir o fluxo da integração.
Corpo da resposta
O cadastro encontrou um limite ou uma configuração já existente. Confira a condição informada antes de repetir a requisição.
Código e explicação do erro retornado pela API.
Código estável do erro.
Explicação do erro em inglês. Em validações, resume a categoria; os detalhes identificam as correções. Use os códigos para tratar a resposta.
Falhas em campos recebidos ou referências enviadas no corpo, com campo, código e explicação. Omitido em erros gerais e quando não há correção de campo a indicar.
Nome público do campo JSON, parâmetro de consulta, parâmetro de rota ou header relacionado ao erro. Campos aninhados e listas preservam o caminho e o índice. $ representa a raiz do corpo JSON.
Motivo do erro no campo, como REQUIRED, INVALID_TAXID, UNKNOWN_FIELD, DUPLICATE_FIELD ou INVALID_TYPE.
Explicação em inglês sobre o problema nesse campo ou parâmetro e a correção disponível. Não use o texto para decidir o fluxo da integração.
Para os erros gerais, consulte Códigos HTTP das respostas.