Webhook configuration

This page covers the management (creation, deletion, modification, testing) of webhook endpoints. For the conceptual model and security, see Concepts → Webhooks.

Model

{
  "id": 301,
  "url": "https://erp.distribuidora-demo.com/maxpay/events",
  "events": [
    "receivable-account.activated",
    "receivable.created",
    "receivable.paid",
    "receivable.settled",
    "settlement.completed"
  ],
  "status": "ACTIVE",
  "secret": "whsec_aB3xY9mNpQ2rTzV5wK7jH8...",
  "secretMaskedTail": "...8fdK",
  "lastDeliveryAt": "2026-05-15T14:30:00-03:00",
  "lastDeliveryStatus": "SUCCESS",
  "creationDate": "2026-04-01T10:00:00-03:00",
  "modificationDate": "2026-05-15T14:30:00-03:00"
}

Field	Type	Description
id	int64	Webhook ID
url	URL	Integrator endpoint. Must be HTTPS
events	array	Events this webhook is subscribed to. Full list in Events
status	enum	ACTIVE, PAUSED, FAILED. After multiple consecutive failures the webhook moves to FAILED (configurable threshold).
secret	string	Secret used to verify the HMAC signature. Only returned on creation or rotation
secretMaskedTail	string	Last 4 characters of the secret, to confirm which one is active
lastDeliveryAt	ISO 8601	Last delivery
lastDeliveryStatus	enum	SUCCESS, FAILED

Endpoints

Method	Path	Description
GET	/v1/webhooks	List configured webhooks
POST	/v1/webhooks	Create a webhook
GET	/v1/webhooks/{id}	Detail
PUT	/v1/webhooks/{id}	Update URL or event list
DELETE	/v1/webhooks/{id}	Delete
POST	/v1/webhooks/{id}/pauses	Pause deliveries
POST	/v1/webhooks/{id}/activations	Resume deliveries
POST	/v1/webhooks/{id}/secret-rotations	Rotate the secret (returns the new one)
POST	/v1/webhooks/{id}/deliveries	Send a test event
GET	/v1/webhooks/{id}/deliveries	Delivery history

Create a webhook

POST /v1/webhooks
Idempotency-Key: setup-erp-prod-001
Content-Type: application/json

{
  "url": "https://erp.distribuidora-demo.com/maxpay/events",
  "events": [
    "receivable-account.activated",
    "receivable.created",
    "receivable.paid",
    "receivable.settled",
    "settlement.completed"
  ]
}

Response

201 Created
Location: /v1/webhooks/301

{
  "id": 301,
  "url": "https://erp.distribuidora-demo.com/maxpay/events",
  "events": [...],
  "status": "ACTIVE",
  "secret": "whsec_aB3xY9mNpQ2rTzV5wK7jH8nM4fdK",
  "secretMaskedTail": "...8fdK",
  ...
}

Save the secret now

The secret field is returned only once, when the webhook is created or rotated. After this request, you will only see secretMaskedTail. If you lose it, you must rotate it with POST /webhooks/{id}/secret-rotations.

Pause and resume

To temporarily pause reception (maintenance, deploy):

POST /v1/webhooks/301/pauses

Events generated while paused are retained and delivered when the webhook resumes. There is a retention window after which retained events are discarded.

POST /v1/webhooks/301/activations

Rotate the secret

To rotate the secret (compromise, policy):

POST /v1/webhooks/301/secret-rotations

{
  "id": 301,
  "secret": "whsec_xY9mNpQ2rT...",
  "secretMaskedTail": "...4hLm",
  ...
}

After rotation, subsequent webhooks arrive signed with the new secret. During a grace window after the rotation, signatures with the previous secret remain valid to give time to update the configuration in the ERP.

Delivery diagnostics

Test delivery

To validate that your endpoint works after configuring it:

POST /v1/webhooks/301/deliveries
Content-Type: application/json

{
  "eventType": "webhook.test"
}

Sends a test event to the configured URL and returns the result of that delivery.

Delivery history

GET /v1/webhooks/301/deliveries?fromDate=2026-05-14&toDate=2026-05-15&status=FAILED

Filters: fromDate, toDate, status, eventType, eventId. Standard pagination. Each delivery includes eventId, eventType, attempt, status and the response code from the endpoint.

Resend a delivery

To manually retry a failed delivery:

POST /v1/webhooks/301/deliveries
Content-Type: application/json

{
  "eventId": "evt_a1b2c3..."
}

Generates a new delivery attempt of the original event. Useful when you have fixed the bug on your endpoint and want to recover missed events.