APG PayAPG Paydocs

Webhooks

Create webhooks

POST/webhooks

Subscribe an endpoint to platform events.

Permissions

Required permission
webhookSubscriptions:update

Requires the `update` action on `webhookSubscriptions` for the supplied runtime context

Request body

This body is a tagged shape: type is always "WebhookCmdCreate". Send it; more variants can be added, and a caller that switches on it keeps working when they are.

Discriminated by type
type = "WebhookCmdCreate"
urlstringrequired

An absolute https (or http) url with a host, at most 2048 characters.

Example https://example.com/callback

eventsarray of WebhookEventType

Event types to deliver.

MerchantCreatedMerchantActivatedMerchantSuspendedMerchantAvailableBalanceUpdatedMerchantBankAccountAddedMerchantPrimaryBankAccountUpdatedPayPlanCreatedPayPlanActivatedPayPlanCompletedPayPlanInDefault
+27 more

PayInFullCreated, PayInFullAccepted, PayInFullAuthorised, PayInFullCompleted, TransactionPaid, TransactionFailed, DisputeCreated, DisputeUpdated, PayoutCreated, PayoutPending, PayoutFailed, PayoutPaid, PayoutReversed, InvoiceIssued, InvoiceDue, InvoicePaymentFailed, InvoicePaid, PaymentSourceCreated, PaymentSourceMethodUpdated, PaymentSourceDeleted, LoanCreated, LoanStatementCreated, LoanStatementIssued, LoanStatementDue, LoanStatementPaid, LoanPaymentFailed, Unknown

descriptionstring

What this subscription is for, in your own words.

metadatamap of any JSON value

Free-form data the platform stores and returns untouched.

secretstring

The secret deliveries are signed with, 16 to 256 characters with no surrounding whitespace. Write-only: it is never returned. Omit it and the platform generates one, which you then cannot read, so send your own if you mean to verify signatures.

merchantIdMchtId

The merchant whose events to deliver. An administrator sends exactly one of this and marketplaceId. A merchant credential may omit both or name only itself. A marketplace credential may omit both, name itself as marketplaceId, or name one of its own merchants here to narrow the subscription to that merchant.

Example mcht_9f2Kd8QpLzXw

marketplaceIdMktpId

The marketplace whose events to deliver. See merchantId.

Example mktp_9f2Kd8QpLzXw

curl -X POST https://api.tst.au.apgpay.dev/webhooks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "WebhookCmdCreate",
  "url": "https://example.com/callback",
  "events": [
    "MerchantCreated"
  ],
  "description": "string",
  "metadata": {
    "yourKey": {}
  },
  "secret": "string",
  "merchantId": "mcht_9f2Kd8QpLzXw",
  "marketplaceId": "mktp_9f2Kd8QpLzXw"
}'

Responses

The response is a tagged shape: type is always "WebhookCreateRspAttributes". Switch on it; subtypes can be added, and a client that already reads it will not break.

Discriminated by type
type = "WebhookCreateRspAttributes"

The resource that was created.

Example
{
  "type": "WebhookCreateRspAttributes",
  "created": {
    "type": "WebhookViewAttributes",
    "webhookId": "webhook_9f2Kd8QpLzXw",
    "merchantId": "mcht_9f2Kd8QpLzXw",
    "marketplaceId": "mktp_9f2Kd8QpLzXw",
    "url": "https://example.com/callback",
    "status": "Active",
    "events": [
      "MerchantCreated"
    ],
    "description": "string",
    "metadata": {
      "yourKey": {}
    },
    "readable": true,
    "consecutiveFailures": 1250,
    "lastDeliveryAt": "2026-08-19T04:21:07Z",
    "lastDeliveryStatus": "Pending",
    "createdAt": "2026-08-19T04:21:07Z",
    "updatedAt": "2026-08-19T04:21:07Z"
  }
}

Error responses