---
title: "Subscription webhook endpoint"
method: POST
path: "/api/v1/subscription-events"
tags: ["Webhook"]
---

# Subscription webhook endpoint

`POST /api/v1/subscription-events`

This endpoint documents the webhook events that PayRetailers will send to your notificationUrl. You should implement this endpoint on your server to receive subscription and payment status updates.

## Request body

- SubscriptionEvent
  - `eventType` string — Type of webhook event. Valid values: subscription_activation, subscription_cancellation, subscription.payment, subscription.payment_schedule, subscription.payment_cancellation
  - `eventId` string — Unique identifier for this event (use for idempotency)
  - `eventDate` string, date-time — UTC timestamp when the event occurred
  - `entityId` string — ID of the entity that triggered the event (Subscription or SubscriptionPayment ID)
  - `status` string — Current status of the entity. For subscriptions: PENDING_USER_AUTH, ACTIVE, CANCELLED, EXPIRED, REJECTED. For payments: PENDING, IN_PROGRESS, PAID, FAILED, CANCELLED
  - `statusDate` string, date-time — UTC timestamp when the status changed
  - `message` string, nullable — Optional message (e.g., cancellation reason)
  - `errorCode` string, nullable — Error code if applicable. Common values: INSUFFICIENT_FUNDS, REJECTED_BY_BANK, CANCELLED_BY_USER, ACCOUNT_CLOSED, AUTHORIZATION_REVOKED, PAYMENT_EXPIRED
  - `errorMessage` string, nullable — Human-readable error message
  - `pspReference` string, nullable — Payment Service Provider reference
  - `end2EndId` string, nullable — End-to-End ID (PIX-specific transaction identifier)
  - `additionalData` AdditionalDataField[], nullable
    - `fieldName` string
    - `fieldType` string
    - `fieldValue` string

## Response `204`

Webhook received successfully - No Content

## Other responses

- `400` — Bad Request

---

[API](https://skmtc.net/payretailers/apis/transaction.md) · [All operations](https://skmtc.net/payretailers/apis/transaction/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/payretailers/transaction/revisions/b022ee3a593d/schema)