Webhooks

Criar ou atualizar a configuração de webhook da organização

Upsert por organizationId. Campos ausentes são preservados; enviar null em uma URL desliga a notificação daquele status. O secret é sempre gerado pelo serviço — nunca aceito no corpo — e só é rotacionado com regenerateSecret: true. O secret é devolvido uma única vez, em data.secret, apenas na resposta que o gerou (primeira configuração ou regenerateSecret: true); nas demais respostas data é null. Ele não pode ser recuperado depois — quem perdeu o valor rotaciona. organizationId é o da sua organização (o mesmo que aparece em organizationId nas carteiras).

PUThttps://api.monkeypay.app/api/v2/webhook/resource/eventsBearer

Fluxo

Antes de chamar

  1. Chamada

    POSTEmitir token bearer

    /resource/auth/token

    Authorization: Bearer <seu-token>

  2. Você

    Publique uma URL HTTPS

    Que responda 2xx em poucos segundos

Esta chamada

PUTConfigurar eventos

/webhook/resource/events

Respostas possíveis

Depois do sucesso

  1. Chamada

    POSTEnviar evento de teste

    /webhook/resource/test-send

    Confirme que a URL recebe

Autorização

BearerRequer autenticação Bearer

Parâmetros

x-customer-idstringcabeçalhoopcional

Opcional. A versão atual da API não lê nem grava este header: a organização é sempre deduzida do token bearer. Enviá-lo não altera o resultado da chamada.

<x-customer-id>

Body

organizationIdstringobrigatório
Tamanho1 ≤ tamanho
org_01J9Z8K3M4N5P6Q7R8S9T0V1W2
typestringopcional

valores: pixbilletted

pix
pendingstring (uri)opcional
<pending>
cancelledstring (uri)opcional
<cancelled>
failedstring (uri)opcional
https://seu-backend.example.com/webhooks/monkeypay
awaitingPaymentstring (uri)opcional
https://seu-backend.example.com/webhooks/monkeypay
expiredstring (uri)opcional
<expired>
createdstring (uri)opcional
<created>
completedstring (uri)opcional
https://seu-backend.example.com/webhooks/monkeypay
processingstring (uri)opcional
<processing>
refundedstring (uri)opcional
https://seu-backend.example.com/webhooks/monkeypay
infractionstring (uri)opcional
<infraction>
maxRetriesintegeropcional
3
retryDelaystringopcional

Intervalo do Postgres, ex. "1 second" ou "00:00:30".

30 seconds
regenerateSecretbooleanopcional

Rotaciona o secret HMAC dos webhooks, invalidando o anterior.

<regenerateSecret>

Respostas

1{
2 "error": null,
3 "success": true,
4 "message": "Organization webhook configuration saved successfully",
5 "data": {
6 "secret": "whsec_9f8e7d6c5b4a3210fedcba9876543210"
7 }
8}

Campos da resposta

errorobjectopcional

`null` no sucesso; mensagem de falha quando `success` é `false`.

<error>
successbooleanopcional
<success>
messagestringopcional
<message>
dataobjectopcional

Presente só quando a chamada gerou um novo secret; caso contrário `null`.

<data>
secretstringopcional
whsec_9f8e7d6c5b4a3210fedcba9876543210
Credenciais

Requisição

1curl --request PUT \
2 --url 'https://api.monkeypay.app/api/v2/webhook/resource/events' \
3 --header 'Content-Type: application/json' \
4 --header 'Authorization: Bearer <seu-token>' \
5 --data '{
6 "organizationId": "org_01J9Z8K3M4N5P6Q7R8S9T0V1W2",
7 "type": "pix",
8 "awaitingPayment": "https://seu-backend.example.com/webhooks/monkeypay",
9 "completed": "https://seu-backend.example.com/webhooks/monkeypay",
10 "failed": "https://seu-backend.example.com/webhooks/monkeypay",
11 "refunded": "https://seu-backend.example.com/webhooks/monkeypay",
12 "maxRetries": 3,
13 "retryDelay": "30 seconds"
14 }'

Resposta

1{
2 "error": null,
3 "success": true,
4 "message": "Organization webhook configuration saved successfully",
5 "data": {
6 "secret": "whsec_9f8e7d6c5b4a3210fedcba9876543210"
7 }
8}