ZypfyDocs Acessar painel
Cartões Virtuais

Cadastrar destino de webhook de cartão

POSThttps://api.zypfy.com/api/v1/cards/webhooks

Em vez de consultar o extrato de tempos em tempos, receba o evento na hora. Cadastre uma ou mais URLs e a Zypfy avisa a cada compra, recusa, carga, estorno ou mudança de status.

A resposta traz um secret — guarde: ele aparece uma única vez. É com ele que você confere a assinatura de cada entrega. Perdeu? Apague o destino e cadastre outro.

Regras da URL: https obrigatório, host público, portas 443 ou 8443. Até 20 destinos por conta. Por padrão o destino recebe todos os eventos; para filtrar, mande events — evento desconhecido é recusado no cadastro, para um erro de digitação não virar "meu webhook não chega".

Cada destino pode ser da conta inteira (padrão) ou de um cartão só, passando cardId: é o caso de quem emite um cartão por cliente e quer o evento no sistema daquele cliente. Se a mesma URL casar pelos dois caminhos, ela recebe uma vez só.

Corpo da requisição

Respostas

201Destino cadastrado. O secret só aparece aqui.
  • webhook
    campos de webhook
    • idstring
      exemplo: 12
    • urlstring (uri)
    • labelstring | null
    • cardIdstring (uuid) | null

      Preenchido quando o destino é de um cartão só.

    • eventsarray de string

      null = todos.

    • activeboolean
    • healthobject
      campos de health
      • lastSuccessAtstring (date-time) | null
      • lastFailureAtstring (date-time) | null
      • lastFailureErrorstring | null
      • consecutiveFailuresinteger
        exemplo: 0
    • createdAtstring (date-time)
    • secretstring

      Aparece UMA única vez. É com ele que você confere a assinatura das entregas.

      exemplo: 9f2c1e0b7a5d43c8...
400URL inválida (não é https, host interno, porta não aceita) ou evento desconhecido.
  • messagestring

    Mensagem humana descrevendo o erro.

    exemplo: Invalid amount.
  • codestring | null

    Código opcional de erro para roteamento no seu sistema.

  • min_amountnumber (float) | null

    Presente em erros de valor abaixo do mínimo configurado.

  • max_amountnumber (float) | null

    Presente em erros de valor acima do máximo absoluto.

  • limitnumber (float) | null

    Presente em erros de limite diário por transação excedido.

  • retry_after_secondsinteger | null

    Presente em erros WITHDRAWAL_COOLDOWN / 429.

409URL já cadastrada neste escopo ou limite de 20 destinos atingido.
  • messagestring

    Mensagem humana descrevendo o erro.

    exemplo: Invalid amount.
  • codestring | null

    Código opcional de erro para roteamento no seu sistema.

  • min_amountnumber (float) | null

    Presente em erros de valor abaixo do mínimo configurado.

  • max_amountnumber (float) | null

    Presente em erros de valor acima do máximo absoluto.

  • limitnumber (float) | null

    Presente em erros de limite diário por transação excedido.

  • retry_after_secondsinteger | null

    Presente em erros WITHDRAWAL_COOLDOWN / 429.