Webhooks

Webhooks are HTTP endpoints that receive notification payloads from the Notifications API. This page covers all webhook destination management operations.

List Destination Types

Returns the available destination types.

Request

GET /v1/destinations

curl Example

curl -X GET "https://api.notifications.paynetworx.cloud/v1/destinations" \
  -H "Authorization: YOUR_API_TOKEN"

Response

{
  "urls": [
    "/v1/destinations/webhook"
  ]
}

---

List Webhooks

Retrieve a paginated list of webhook destinations.

Request

GET /v1/destinations/webhook

curl Example

curl -X GET "https://api.notifications.paynetworx.cloud/v1/destinations/webhook?limit=10&offset=0" \
  -H "Authorization: YOUR_API_TOKEN"

Query Parameters

Parameter	Type	Default	Description
limit	integer	10	Maximum number of results (0-1000)
offset	integer	0	Number of results to skip

Response

{
  "webhook": [
    {
      "id": "9603F4B2-1874-42FE-A2BC-F7B45C45A9D6",
      "name": "Production Webhook",
      "description": "Main production endpoint",
      "http_endpoint_url": "https://example.com/webhook",
      "method": "POST",
      "headers": {},
      "confirmed": true,
      "disabled": false,
      "created": "2024-01-15T10:30:00Z"
    }
  ]
}

---

Create Webhook

Create a new webhook destination.

Request

POST /v1/destinations/webhook
Content-Type: application/json

curl Example

curl -X POST "https://api.notifications.paynetworx.cloud/v1/destinations/webhook" \
  -H "Authorization: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Webhook",
    "description": "Production webhook endpoint",
    "http_endpoint_url": "https://example.com/webhook",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer my-secret-token"
    }
  }'

Request Body

Field	Type	Required	Description
name	string	Yes	Name for the webhook (1-124 characters)
description	string	No	Description of the webhook (1-256 characters)
http_endpoint_url	string	Yes	URL to send events to (must be valid URI, 1-124 characters)
method	string	No	HTTP method: POST (default) or PUT
headers	object	No	Additional headers to include in requests (e.g., authentication headers)
disabled	boolean	No	If true, no events will be sent to this endpoint (default: false)
confirmed	boolean	No	Override confirmation status

Example Request

{
  "name": "My Webhook",
  "description": "Production webhook endpoint",
  "http_endpoint_url": "https://example.com/webhook",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer my-secret-token"
  }
}

Response

{
  "id": "9603F4B2-1874-42FE-A2BC-F7B45C45A9D6",
  "name": "My Webhook",
  "description": "Production webhook endpoint",
  "http_endpoint_url": "https://example.com/webhook",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer my-secret-token"
  },
  "confirmed": false,
  "disabled": false,
  "created": "2024-01-15T10:30:00Z",
  "url": "/v1/destinations/webhook/9603F4B2-1874-42FE-A2BC-F7B45C45A9D6"
}

Error Responses

Status	Description
400	Bad Request - Invalid input parameters
403	Forbidden - Insufficient permissions

---

Get Webhook

Retrieve details of a specific webhook destination.

Request

GET /v1/destinations/webhook/{id}

curl Example

curl -X GET "https://api.notifications.paynetworx.cloud/v1/destinations/webhook/9603F4B2-1874-42FE-A2BC-F7B45C45A9D6" \
  -H "Authorization: YOUR_API_TOKEN"

Path Parameters

Parameter	Type	Description
id	UUID	Webhook destination ID

Response

{
  "id": "9603F4B2-1874-42FE-A2BC-F7B45C45A9D6",
  "name": "My Webhook",
  "description": "Production webhook endpoint",
  "http_endpoint_url": "https://example.com/webhook",
  "method": "POST",
  "headers": {},
  "confirmed": true,
  "disabled": false,
  "created": "2024-01-15T10:30:00Z"
}

Error Responses

Status	Description
400	Bad Request - Invalid webhook ID

---

Update Webhook

Update an existing webhook destination.

Request

PUT /v1/destinations/webhook/{id}
Content-Type: application/json

curl Example

curl -X PUT "https://api.notifications.paynetworx.cloud/v1/destinations/webhook/9603F4B2-1874-42FE-A2BC-F7B45C45A9D6" \
  -H "Authorization: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Webhook Name",
    "description": "Updated description",
    "disabled": false
  }'

Path Parameters

Parameter	Type	Description
id	UUID	Webhook destination ID

Request Body

Field	Type	Description
name	string	Name for the webhook (1-124 characters)
description	string	Description of the webhook (1-256 characters)
http_endpoint_url	string	URL to send events to
method	string	HTTP method: POST or PUT
headers	object	Additional headers to include in requests
disabled	boolean	If true, no events will be sent to this endpoint

Example Request

{
  "name": "Updated Webhook Name",
  "description": "Updated description",
  "disabled": false
}

Response

{
  "id": "9603F4B2-1874-42FE-A2BC-F7B45C45A9D6",
  "name": "Updated Webhook Name",
  "description": "Updated description",
  "http_endpoint_url": "https://example.com/webhook",
  "method": "POST",
  "headers": {},
  "confirmed": true,
  "disabled": false,
  "created": "2024-01-15T10:30:00Z"
}

Error Responses

Status	Description
400	Bad Request - Invalid input parameters

---

Delete Webhook

Delete a webhook destination.

Request

DELETE /v1/destinations/webhook/{id}

curl Example

curl -X DELETE "https://api.notifications.paynetworx.cloud/v1/destinations/webhook/9603F4B2-1874-42FE-A2BC-F7B45C45A9D6" \
  -H "Authorization: YOUR_API_TOKEN"

Path Parameters

Parameter	Type	Description
id	UUID	Webhook destination ID

Response

Returns 204 No Content on success.

Error Responses

Status	Description
400	Bad Request - Invalid webhook ID

---

Resend Confirmation

Resend the confirmation request to a webhook destination. Use this if the initial confirmation was not received or failed.

Request

POST /v1/destinations/webhook/{id}/confirm

curl Example

curl -X POST "https://api.notifications.paynetworx.cloud/v1/destinations/webhook/9603F4B2-1874-42FE-A2BC-F7B45C45A9D6/confirm" \
  -H "Authorization: YOUR_API_TOKEN"

Path Parameters

Parameter	Type	Description
id	UUID	Webhook destination ID

Response

{
  "status": "success",
  "message": "Confirmation event queued for webhook"
}

Error Responses

Status	Description
400	Bad Request - Invalid webhook ID
403	Forbidden - Insufficient permissions

---

Testing Your Webhook

After creating a webhook and linking it to a subscription, you can send a test notification to verify your integration before waiting for live events.

Send Test Event

curl -X POST "https://api.notifications.paynetworx.cloud/v1/subscriptions/{type}/{subscription_id}/test" \
  -H "Authorization: YOUR_API_TOKEN"

Replace {type} with the subscription type (e.g., transaction, merchant_ach_funding_item, merchant_card_funding_group) and {subscription_id} with your subscription UUID.

What to Expect

When you send a test event:

1. A sample notification payload is generated for the subscription type
2. The payload is sent to all confirmed webhook destinations linked to that subscription
3. Your webhook receives the payload with the same signature format as live events

Verifying Test Receipt

Your webhook endpoint should:

1. Receive an HTTP POST (or PUT, depending on configuration) request
2. Parse the JSON payload
3. Verify the X-Webhook-Signature header (see Signature Verification)
4. Return a 2xx status code to acknowledge receipt

TIP

Use test events during initial integration to ensure your webhook handler correctly processes payloads and verifies signatures before going live.

---

Webhook Delivery Behavior

Retry Logic

If your webhook endpoint fails to respond with a 2xx status code, the notification system will retry delivery:

• Failed deliveries are retried automatically
• Each delivery attempt is tracked in the event history
• You can manually resend failed events via the Event History API

Delivery Metadata

Each webhook delivery includes metadata about the attempt:

Field	Description
attempt	The delivery attempt number
timestamp	When this attempt was made

Best Practices

• Respond quickly: Return a 2xx response within a few seconds to avoid timeouts
• Process asynchronously: Queue webhook payloads for background processing rather than processing inline
• Implement idempotency: Use the event IDs to detect and handle duplicate deliveries
• Monitor failures: Check event history regularly for failed deliveries

---

Webhook Object Reference

Field	Type	Description
id	UUID	Unique identifier for the webhook
name	string	Name of the webhook (1-124 characters)
description	string	Description of the webhook (1-256 characters)
http_endpoint_url	string	URL where events are sent
method	string	HTTP method used (POST or PUT)
headers	object	Custom headers included in requests
confirmed	boolean	Whether the webhook has been confirmed
disabled	boolean	Whether the webhook is disabled
created	string	ISO 8601 timestamp of creation