Reference

Webhooks

List webhook subscriptions#

GET/webhook-subscriptions

Authorization: API-Key · Rate limit 60 requests / 60 s (sandbox 10 in total)

curl "https://macaaw.com/public/v1/webhook-subscriptions" \
  -H "Authorization: API-Key $MACAAW_API_KEY"

Responses#

200OKapplication/json · WebhookSubscriptionList
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

200 response

{
  "results": [
    {
      "uuid": "string",
      "name": "string",
      "url": "https://example.com/webhooks/macaaw",
      "triggers": [
        "document_state_changed"
      ],
      "active": true,
      "sandbox": true,
      "deactivated_reason": null,
      "date_created": "2026-10-30T11:35:00.000000Z",
      "date_modified": "2026-10-30T11:35:00.000000Z"
    }
  ]
}

Create a webhook subscription#

POST/webhook-subscriptions

Authorization: API-Key · Rate limit 60 requests / 60 s (sandbox 10 in total)

https only, public hosts only (private, loopback, link-local and metadata addresses are refused). The shared key is shown once.

Headers#

Idempotency-Keystring
Replays the first response for 24 hours.
max length 255

Request body#

application/json

namestringrequired
min length 1 · max length 80
urlstring (uri)required
max length 2048
triggersarray of stringrequired
document_state_changedrecipient_completeddocument_completed_pdf_readydocument_updateddocument_deleteddocument_creation_failedtask_completedtask_failed
min items 1 · max items 8
activeboolean
sandboxboolean

curl -X POST "https://macaaw.com/public/v1/webhook-subscriptions" \
  -H "Authorization: API-Key $MACAAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","url":"https://example.com/webhooks/macaaw","triggers":["document_state_changed"],"active":true,"sandbox":true}'

Responses#

201OKapplication/json · WebhookSubscriptionCreated
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
409Wrong stateapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

201 response

{
  "uuid": "string",
  "name": "string",
  "url": "https://example.com/webhooks/macaaw",
  "triggers": [
    "document_state_changed"
  ],
  "active": true,
  "sandbox": true,
  "deactivated_reason": null,
  "date_created": "2026-10-30T11:35:00.000000Z",
  "date_modified": "2026-10-30T11:35:00.000000Z",
  "shared_key": "string"
}

Get a webhook subscription#

GET/webhook-subscriptions/{uuid}

Authorization: API-Key · Rate limit 60 requests / 60 s (sandbox 10 in total)

Path parameters#

uuidstringrequired

curl "https://macaaw.com/public/v1/webhook-subscriptions/$UUID" \
  -H "Authorization: API-Key $MACAAW_API_KEY"

Responses#

200OKapplication/json · WebhookSubscription
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

200 response

{
  "uuid": "string",
  "name": "string",
  "url": "https://example.com/webhooks/macaaw",
  "triggers": [
    "document_state_changed"
  ],
  "active": true,
  "sandbox": true,
  "deactivated_reason": null,
  "date_created": "2026-10-30T11:35:00.000000Z",
  "date_modified": "2026-10-30T11:35:00.000000Z"
}

Update a webhook subscription#

PATCH/webhook-subscriptions/{uuid}

Authorization: API-Key · Rate limit 60 requests / 60 s (sandbox 10 in total)

Path parameters#

uuidstringrequired

Request body#

application/json

namestring
min length 1 · max length 80
urlstring (uri)
max length 2048
triggersarray of string
document_state_changedrecipient_completeddocument_completed_pdf_readydocument_updateddocument_deleteddocument_creation_failedtask_completedtask_failed
min items 1 · max items 8
activeboolean

curl -X PATCH "https://macaaw.com/public/v1/webhook-subscriptions/$UUID" \
  -H "Authorization: API-Key $MACAAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","url":"https://example.com/webhooks/macaaw","triggers":["document_state_changed"],"active":true}'

Responses#

200OKapplication/json · WebhookSubscription
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
409Wrong stateapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

200 response

{
  "uuid": "string",
  "name": "string",
  "url": "https://example.com/webhooks/macaaw",
  "triggers": [
    "document_state_changed"
  ],
  "active": true,
  "sandbox": true,
  "deactivated_reason": null,
  "date_created": "2026-10-30T11:35:00.000000Z",
  "date_modified": "2026-10-30T11:35:00.000000Z"
}

Delete a webhook subscription#

DELETE/webhook-subscriptions/{uuid}

Authorization: API-Key · Rate limit 60 requests / 60 s (sandbox 10 in total)

Path parameters#

uuidstringrequired

curl -X DELETE "https://macaaw.com/public/v1/webhook-subscriptions/$UUID" \
  -H "Authorization: API-Key $MACAAW_API_KEY"

Responses#

204No content
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
409Wrong stateapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

Regenerate the shared key#

POST/webhook-subscriptions/{uuid}/shared-key

Authorization: API-Key · Rate limit 60 requests / 60 s (sandbox 10 in total)

Path parameters#

uuidstringrequired

curl -X POST "https://macaaw.com/public/v1/webhook-subscriptions/$UUID/shared-key" \
  -H "Authorization: API-Key $MACAAW_API_KEY"

Responses#

200OKapplication/json · SharedKey
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
409Wrong stateapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

200 response

{
  "uuid": "string",
  "shared_key": "string"
}

Delivery history#

GET/webhook-events

Authorization: API-Key · Rate limit 60 requests / 60 s (sandbox 10 in total)

Query parameters#

subscriptionstring (uuid)
statusstring
pendingdeliveredfailed
pageinteger
min 1 · max 100000 · default 1
countinteger
min 1 · max 100 · default 50

curl "https://macaaw.com/public/v1/webhook-events" \
  -H "Authorization: API-Key $MACAAW_API_KEY"

Responses#

200OKapplication/json · WebhookEventList
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

200 response

{
  "results": [
    {
      "id": "string",
      "subscription": "string",
      "event": "string",
      "events": [
        "string"
      ],
      "status": "pending",
      "attempts": 1,
      "http_status": 1,
      "error": "string",
      "response": "string",
      "date_created": "2026-10-30T11:35:00.000000Z",
      "delivered_at": "2026-10-30T11:35:00.000000Z",
      "next_attempt_at": "2026-10-30T11:35:00.000000Z"
    }
  ]
}

Resend a delivery now#

POST/webhook-events/{id}/resend

Authorization: API-Key · Rate limit 60 requests / 60 s (sandbox 10 in total)

Path parameters#

idstringrequired

curl -X POST "https://macaaw.com/public/v1/webhook-events/$ID/resend" \
  -H "Authorization: API-Key $MACAAW_API_KEY"

Responses#

200OKapplication/json · WebhookEvent
400Validation errorapplication/json · Error
401Missing, unknown or revoked API keyapplication/json · Error
403Plan or permissionapplication/json · Error
404Not foundapplication/json · Error
409Wrong stateapplication/json · Error
429Rate limitedapplication/json · Error
Headers: Retry-After

200 response

{
  "id": "string",
  "subscription": "string",
  "event": "string",
  "events": [
    "string"
  ],
  "status": "pending",
  "attempts": 1,
  "http_status": 1,
  "error": "string",
  "response": "string",
  "date_created": "2026-10-30T11:35:00.000000Z",
  "delivered_at": "2026-10-30T11:35:00.000000Z",
  "next_attempt_at": "2026-10-30T11:35:00.000000Z"
}