DocPay: webhooks

A webhook automatically notifies your system about a completed payment. Configuration has two steps: register a webhook, then assign it to a product. From then on, events (e.g. successful payment) for that product are sent to your endpoint. All requests are authorized with an API key sent in the X-API-KEY header.

Examples use the sandbox environment: https://gateway-api.sandbox.paymove.io. You need your partnerId and the productId of a product created in the DocPay: basic integration tutorial.

Step 1: Register webhook

curl --request POST \
  --url https://gateway-api.sandbox.paymove.io/api/pay/plugin/webhook \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "name": "PaymentSuccessHook",
    "endpoint": "https://example.com/webhooks/payment-success",
    "method": "POST",
    "requestTemplate": {
      "productId": "productId",
      "event": "event"
    },
    "responseTemplate": {
      "status": "ok"
    },
    "expectedCode": 200,
    "expectedResponse": "{ \"status\": \"ok\" }",
    "retries": 3,
    "partnerId": "78562c79-2f5c-4415-8af4-c871eea92ef2",
    "type": "PAYMENT",
    "headers": {
      "Authorization": ["Bearer abc123"],
      "Content-Type": ["application/json"]
    }
  }'

Field	Description
`name`	Webhook name (visible in configuration).
`endpoint`	URL Paymove sends the request to.
`method`	HTTP method (e.g. `POST`).
`requestTemplate`	Request body template (variables substituted by Paymove).
`responseTemplate`	Expected response structure from the partner.
`expectedCode`	Expected HTTP response code (e.g. 200).
`expectedResponse`	Expected response body (e.g. `{ "status": "ok" }`).
`retries`	Number of retries on failure.
`partnerId`	Partner identifier (assigned by Paymove).
`type`	Event type - for payment notifications: `PAYMENT`.
`headers`	Headers sent with the request (e.g. `Authorization`, `Content-Type`).

Response (200):

{
  "id": "18e19688-bdda-4843-8777-0f04d0143c77",
  "name": "PaymentSuccessHook",
  "endpoint": "https://example.com/webhooks/payment-success",
  "method": "POST",
  "requestTemplate": {
    "productId": "productId",
    "event": "event"
  },
  "responseTemplate": {
    "status": "ok"
  },
  "expectedCode": 200,
  "expectedResponse": "{ \"status\": \"ok\" }",
  "retries": 3,
  "type": "PAYMENT",
  "headers": {
    "Authorization": ["Bearer abc123"],
    "Content-Type": ["application/json"]
  },
  "signingSecret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

The id field in the response is the webhook identifier (webhookId), which you will use in step 2.

The response contains a signingSecret - a secret for verifying the signature of requests coming from Paymove. Store it securely in your system and do not expose it publicly.

Step 2: Assign webhook to product

The webhook only becomes active after linking it to a product. Replace webhookId (from step 1) and productId in the URL.

curl --request POST \
  --url https://gateway-api.sandbox.paymove.io/api/pay/plugin/webhook/18e19688-bdda-4843-8777-0f04d0143c77/products/d0a834f9-94a4-4b3a-aa10-27d911e3633f \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Response (200): the webhook object (same as in step 1), confirming the link. From then on, payment events for this product are sent to your endpoint.

Verify the configuration

You can check the products linked to a webhook with:

curl --url https://gateway-api.sandbox.paymove.io/api/pay/plugin/webhook/18e19688-bdda-4843-8777-0f04d0143c77/products \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Response (200): an array of products linked to the webhook:

[
  {
    "id": "d0a834f9-94a4-4b3a-aa10-27d911e3633f",
    "name": "Test Product",
    "productType": "PAY",
    "status": "ACTIVE"
  }
]

How does Paymove call your endpoint?

After a completed payment, Paymove sends a request to your endpoint following requestTemplate and the configured headers. Your system should respond with expectedCode and expectedResponse (e.g. 200 and { "status": "ok" }). On failure, Paymove retries as many times as set in retries.

What’s next?

REST API

Full webhook endpoint reference: list, details, update.

Introduction

Integrations

Tutorials

Help

Resources

Step 1: Register webhook

Step 2: Assign webhook to product

Verify the configuration

How does Paymove call your endpoint?

What’s next?

REST API

​Step 1: Register webhook

​Step 2: Assign webhook to product

​Verify the configuration

​How does Paymove call your endpoint?

​What’s next?

REST API

Step 1: Register webhook

Step 2: Assign webhook to product

Verify the configuration

How does Paymove call your endpoint?

What’s next?