Configure Webhooks

Configure where DigetPay sends payment notifications for your merchant account, including payment success, failure, capture, and refund events.

After configuring your webhook, implement your endpoint using Receiving Webhooks.

Merchant Portal (UI)

The easiest way to configure a webhook is through the DigetPay Merchant Portal.

1. Log in to the DigetPay Merchant Portal.
2. Navigate to Settings → Webhooks.
3. Add your HTTPS endpoint URL.
4. Configure the required webhook settings.
5. Save the configuration.
6. Complete a test transaction and verify that your endpoint receives the notification.

Webhook Configuration Flow

sequenceDiagram
    autonumber
    participant Merchant as Merchant
    participant Portal as DigetPay Merchant Portal
    participant Config as Webhook Configuration

    Merchant->>Portal: Add webhook URL and settings
    Portal->>Config: Validate and save configuration
    Config-->>Portal: Configuration saved
    Portal-->>Merchant: Webhook configured

Create a Webhook

Webhooks can also be managed programmatically through the Merchant Portal API.

Request

POST /merchant/account/webhooks

Request Payload

{
  "url": "https://yourstore.com/webhooks/digetpay",
  "events": [
    "sale.approved",
    "refund.completed"
  ],
  "active": true
}

Sequence

sequenceDiagram
    autonumber
    participant Merchant as Merchant API Client
    participant API as DigetPay Portal API
    participant Config as Webhook Configuration

    Merchant->>API: POST /merchant/account/webhooks
    API->>Config: Validate and save webhook
    Config-->>API: Configuration saved
    API-->>Merchant: 201 Created

Success Response

{
  "success": {
    "status": 201,
    "body": {
      "id": "wh_abc123",
      "url": "https://yourstore.com/webhooks/digetpay",
      "events": [
        "sale.approved",
        "refund.completed"
      ],
      "active": true
    }
  }
}

Invalid Request Response

{
  "failed": {
    "status": 400,
    "body": {
      "statusCode": 400,
      "message": "Invalid webhook URL",
      "error": "Bad Request"
    }
  }
}

Unauthorized Response

{
  "failed_unauthorized": {
    "status": 401,
    "body": {
      "statusCode": 401,
      "message": "Unauthorized",
      "error": "Unauthorized"
    }
  }
}

Update a Webhook

Use the webhook ID returned when the webhook was created.

Request

PUT /merchant/account/webhooks/{webhookId}

Request Payload

{
  "url": "https://yourstore.com/webhooks/digetpay-v2",
  "active": true
}

Sequence

sequenceDiagram
    autonumber
    participant Merchant as Merchant API Client
    participant API as DigetPay Portal API
    participant Config as Webhook Configuration

    Merchant->>API: PUT /merchant/account/webhooks/{webhookId}
    API->>Config: Validate and update configuration
    Config-->>API: Configuration updated
    API-->>Merchant: 200 Updated webhook

Delete a Webhook

Use the webhook ID associated with the endpoint you want to remove.

Request

DELETE /merchant/account/webhooks/{webhookId}

Sequence

sequenceDiagram
    autonumber
    participant Merchant as Merchant API Client
    participant API as DigetPay Portal API
    participant Config as Webhook Configuration

    Merchant->>API: DELETE /merchant/account/webhooks/{webhookId}
    API->>Config: Remove webhook configuration
    Config-->>API: Configuration deleted
    API-->>Merchant: 204 No Content

Callback URL for S2S Integrations

For server-to-server integrations, DigetPay forwards supported gateway notifications to the merchant callback URL configured for the integration.

Example callback configuration:

{
  "method": "POST",
  "url": "https://yourstore.com/webhooks/digetpay",
  "contentType": "application/json"
}

For S2S payment flows, DigetPay receives gateway callbacks through the relevant callback endpoint:

POST /v1/payment/s2s/callback/{merchantId}

For payload handling and transaction verification, see Receiving Webhooks.

Portal API Access

The Portal API requires a Portal Bearer Token for authentication.

Before using the webhook management endpoints, make sure you have completed the Portal API authentication flow.

For details on:

• Obtaining a Portal Bearer Token
• Authenticating with the Merchant Portal
• Using the Authorization: Bearer <token> header
• Token expiration and re-authentication
• Credential security and environment separation

see Authentication & Credentials.

Authorization Header

Include the Portal Bearer Token in requests to protected Portal API endpoints:

Authorization: Bearer YOUR_PORTAL_TOKEN

Portal API Endpoints

Staging vs Production

Register separate webhook URLs or separate paths for each environment.

Webhook Management Checklist

Before using a webhook in production, verify that:

• The endpoint uses HTTPS.
• The endpoint is publicly reachable.
• The server accepts POST requests.
• The endpoint accepts application/json.
• The webhook is registered under the correct merchant account.
• The webhook is configured in the correct environment.
• The endpoint returns HTTP 200 within the expected response time.
• Incoming events are logged for troubleshooting.
• Duplicate events are handled safely.
• Transaction status is confirmed using the documented webhook or status verification process.

Related Guides

API Reference →