Skip to main content

Webhooks API

Configure webhooks to receive real-time notifications when events occur.

Get Webhook​

Retrieve the webhook configuration for a project.

GET /projects/{projectId}/webhook

Response​

{
  "id": "whk_abc123",
  "url": "https://example.com/webhook/maes",
  "events": ["card.enabled", "card.disabled"],
  "status": "active",
  "secretPrefix": "whsec_a1b2c3d4",
  "description": "Production webhook",
  "failureCount": 0,
  "lastTriggeredAt": "2025-12-27T16:24:05.712Z",
  "verifiedAt": "2025-12-26T10:30:00.000Z",
  "createdAt": "2025-12-26T10:30:00.000Z",
  "updatedAt": "2025-12-27T16:24:05.712Z"
}

Create Webhook​

Configure a webhook endpoint for a project.

POST /projects/{projectId}/webhook

Request Body​

FieldTypeRequiredDescription
urlstringYesHTTPS webhook endpoint URL
eventsstring[]YesEvents to subscribe to
descriptionstringNoOptional description

Request​

curl -X POST "https://api.maes-platform.nuvoni.eu/v1/projects/{projectId}/webhook" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook/maes",
    "events": ["card.enabled", "card.disabled", "sync.completed"],
    "description": "Production webhook"
  }'

Response​

{
  "id": "whk_abc123",
  "url": "https://example.com/webhook/maes",
  "events": ["card.enabled", "card.disabled", "sync.completed"],
  "status": "active",
  "secret": "whsec_a1b2c3d4e5f6g7h8...",
  "secretPrefix": "whsec_a1b2c3d4",
  "createdAt": "2025-12-26T10:30:00.000Z"
}
warning

The full secret is only returned once on creation — store it securely!

Update Webhook​

Update webhook configuration.

PATCH /projects/{projectId}/webhook

Request Body​

All fields are optional. Only provide fields you want to update.

{
  "url": "https://example.com/new-webhook-path",
  "events": ["card.enabled", "card.disabled"],
  "description": "Updated webhook"
}

Delete Webhook​

Remove webhook configuration.

DELETE /projects/{projectId}/webhook

Returns 204 No Content on success.

Test Webhook​

Send a test event to verify your webhook endpoint.

POST /projects/{projectId}/webhook/test

Response​

{
  "success": true,
  "statusCode": 200,
  "duration": 150,
  "message": "Test event delivered successfully"
}

Rotate Secret​

Generate a new webhook secret.

POST /projects/{projectId}/webhook/rotate-secret

Response​

{
  "secret": "whsec_new_secret_value..."
}
warning

The new secret is only returned once — store it securely!

Enable/Disable Webhook​

POST /projects/{projectId}/webhook/enable
POST /projects/{projectId}/webhook/disable

Returns the updated webhook configuration.