The API reference isn't available right now
This instance couldn't load its API specification. The reference returns as soon as the specification is readable again.
Back to the API reference
No such operation
This instance documents no operation under that identifier. It may have been renamed, or it may belong to a feature this installation hasn't enabled.
Back to the API reference
This reference may be out of date
This instance couldn't reach its API specification on the last attempt, so this page shows the copy fetched before that. Anything added or changed since then is missing here, and the reference updates itself as soon as the specification is readable again. Last fetched 2026-11-12 05:58 UTC.
API reference
/
Notifications
Opens a listen session for the caller's merchant and returns its signing secret, once.
POST
/api/notifications/listen-sessions
deprecated
Requires: Notifications.ListenSessions.Listen, merchant scope.
Requires API key scope:
webhooks
()
The secret is not recoverable afterwards: only a hash of it is stored. Losing it means opening
a new session.
Signed in, you can send this request to your own sandbox merchant from the console
and read the answer.
Sign in to try it .
On this page
Example request
Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key.
The request body is a CreateListenSessionInput. See the Request body section below for its fields.
Code sample language >_
cURL PS
PowerShell TS
TypeScript C#
C# Py
Python
Copythe install command for cURL
Copied
Copy failed
cURL CopycURL
Copied
Copy failed
curl -X POST "{{BASE_URL}}/api/notifications/listen-sessions" \
-H "api-key: {{API_KEY}}" \
-H "Content-Type: application/json" \
-d '{
"eventTypes": [
""
]
}'
Copythe install command for PowerShell
Copied
Copy failed
PowerShell CopyPowerShell
Copied
Copy failed
$headers = @{
'api-key' = '{{API_KEY}}'
}
$body = @'
{
"eventTypes": [
""
]
}
'@
$response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/notifications/listen-sessions' `
-Headers $headers -ContentType 'application/json' -Body $bodynpm install @winkpg/winkpg-api
Copythe install command for TypeScript (SDK)
Copied
Copy failed
TypeScript (SDK) CopyTypeScript (SDK)
Copied
Copy failed
import { Configuration, NotificationsApi } from '@winkpg/winkpg-api';
const api = new NotificationsApi(new Configuration({
basePath: '{{BASE_URL}}',
apiKey: '{{API_KEY}}',
}));
const { data } = await api.notificationsCreateListenSessions({
"eventTypes": [
""
]
});
Copythe install command for TypeScript (raw HTTP)
Copied
Copy failed
TypeScript (raw HTTP) CopyTypeScript (raw HTTP)
Copied
Copy failed
const response = await fetch('{{BASE_URL}}/api/notifications/listen-sessions', {
method: 'POST',
headers: {
"api-key": "{{API_KEY}}",
"Content-Type": "application/json",
},
body: JSON.stringify({
"eventTypes": [
""
]
}),
});
const data = await response.json();dotnet add package WinkPg.Api.Client
Copythe install command for C# (SDK)
Copied
Copy failed
C# (SDK) CopyC# (SDK)
Copied
Copy failed
using WinkPg.Api.Client.Api;
using WinkPg.Api.Client.Client;
using System.Text.Json;
var config = new Configuration { BasePath = "{{BASE_URL}}" };
config.AddApiKey("api-key", "{{API_KEY}}");
var api = new NotificationsApi(config);
var body = JsonSerializer.Deserialize<CreateListenSessionInput>("""
{
"eventTypes": [
""
]
}
""");
var result = await api.NotificationsCreateListenSessionsAsync(body);
Copythe install command for C# (raw HTTP)
Copied
Copy failed
C# (raw HTTP) CopyC# (raw HTTP)
Copied
Copy failed
using System.Text;
using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") };
var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/notifications/listen-sessions");
request.Headers.Add("api-key", "{{API_KEY}}");
request.Content = new StringContent("""
{
"eventTypes": [
""
]
}
""", Encoding.UTF8, "application/json");
var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();pip install winkpg-api
Copythe install command for Python (SDK)
Copied
Copy failed
Python (SDK) CopyPython (SDK)
Copied
Copy failed
import winkpg_api
configuration = winkpg_api.Configuration(host="{{BASE_URL}}")
configuration.api_key["ApiKey"] = "{{API_KEY}}"
with winkpg_api.ApiClient(configuration) as client:
api = winkpg_api.NotificationsApi(client)
body = winkpg_api.CreateListenSessionInput.from_dict({
"eventTypes": [
""
]
})
result = api.notifications_create_listen_sessions(body)pip install requests
Copythe install command for Python (raw HTTP)
Copied
Copy failed
Python (raw HTTP) CopyPython (raw HTTP)
Copied
Copy failed
import requests
headers = {
"api-key": "{{API_KEY}}",
"Content-Type": "application/json",
}
body = {
"eventTypes": [
""
]
}
response = requests.request(
"POST",
"{{BASE_URL}}/api/notifications/listen-sessions",
headers=headers,
json=body,
)
response.raise_for_status()
data = response.json()
Parameters
Name
In
Type
Description
suppressNulls
required
query
boolean
If true, omit properties with null values.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Request body
application/json
, required
Field
Type
Description
eventTypes
required
array of string
array of
Event types to stage. Empty means every event type the caller may see, resolved once at
creation and then fixed for the session's lifetime.
nullable max items 50
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
label
required
string
Optional human label, so an operator's list reads sensibly.
nullable max length 128
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
ttlMinutes
required
integer (int32)
Requested session lifetime in minutes, renewed by poll activity. Clamped server-side; a value
outside the supported range is corrected, not refused.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
This request body has no documented fields.
Responses
Response status
200
OK
The session was opened. The body carries the signing secret, once.
Body:
ListenSessionCreatedDto
ListenSessionCreatedDto
Each item has these fields.
Field
Type
Description
id
required
string (uuid)
The session id, used on the poll, sample and end routes.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
signingSecret
required
string
The signing secret, shown exactly once.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
merchantId
required
string (uuid)
The merchant the session is scoped to.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
eventTypes
required
array of string
array of
The resolved event types the session stages.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
expiresAtUtc
required
string (date-time)
When the session expires unless polling renews it.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
ttlMinutes
required
integer (int32)
The clamped session lifetime, in minutes, that each poll renews by.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
This response has no documented body fields.
403
Forbidden
The caller has no merchant context, so there is no single merchant to scope a session to.
Body:
Each item has these fields.
This response has no body.
429
Too Many Requests
The request was refused because a rate limit was exceeded, or because something a later retry can clear stopped it. A rate limit refusal carries an `application/problem+json` body: wait at least the interval `Retry-After` names before retrying, then back off. Limits are tuned per deployment, so read the allowance from the response headers rather than assuming a fixed ceiling. Any other refusal carries the standard error envelope as `application/json`, and its `error.code` names the cause.
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
Field
Type
Description
error
required
RemoteServiceErrorInfo
RemoteServiceErrorInfo
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
This response has no documented body fields.
Errors
default
default
The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The error reference lists the values `error.code` can take. The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The error reference lists the values `error.code` can take.
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
Field
Type
Description
error
required
RemoteServiceErrorInfo
RemoteServiceErrorInfo
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Fields of RemoteServiceErrorInfo:
Field
Type
Description
code
required
string
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
message
required
string
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
details
required
string
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
data
required
object
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
validationErrors
required
array of RemoteServiceValidationErrorInfo
array of RemoteServiceValidationErrorInfo
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
This body has no documented fields.
This response has no documented body fields.
Next steps