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

# Subscription webhook endpoint

`POST /api/v1/subscription-events`

## Request

- Base URL: `https://api.payretailers.com`
- URL: `https://api.payretailers.com/api/v1/subscription-events`
- Auth: HTTP basic

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.dev/payretailers/apis/subscriptions-module-api.md) - [All operations](https://skmtc.dev/payretailers/apis/subscriptions-module-api/llms.txt) - [OpenAPI document](https://skmtc.dev/payretailers/apis/subscriptions-module-api/revisions/dd2464c871f8?raw)