Send a test event to your webhook

Sends ONE signed call, right now, to the webhook address you saved under notification settings, with a sample of what an event of the type you name carries, and answers how it went: whether your receiver answered with a 2xx status, which status, how long it took, and why not when it did not arrive. Use it to write and try your receiver (above all the signature check) before a real event happens.

The call is made like every other: it is signed with your current secret (and the previous one while a rotation overlaps), it carries the headers webhook-id, webhook-timestamp, webhook-signature and x-widgetic-event (the event type), and its body is { "id", "type", "createdAt", "partnerId", "data" }. Three things differ. id starts with evt_test_ and is new every time, so a receiver that remembers ids can tell a test from an event and drop it. data holds made-up values of the shape a real event of that type carries (PartnerNotification describes each), never anything about your account. And the call is made once: it is not tried again, nothing is stored, and it appears neither in the delivery log nor in the notification list.

It is sent whatever webhookEvents says: a test is not filtered by what you subscribed to. The answer is 200 whether or not your receiver took the call (read delivered); a call that gets no answer within ten seconds is given up and reported as a timeout.

A webhook address and a signing secret must be saved first (updatePartnerNotificationSettings); until then the answer is 409. This needs an API key with full access, and Idempotency-Key is required: a retry with the same key gets the first answer back and no second call is made. The caller must be the person who administers the partner, or a Widgetic administrator. Five tests a minute.

POST /partners/{partnerId}/notifications/test-event

TypeScript SDK

TypeScript

import { randomUUID } from 'node:crypto';
import { Configuration, PartnersApi } from '@widgetic/api-sdk-ts';

const partnersApi = new PartnersApi(new Configuration({ apiKey: 'YOUR_API_KEY' }));

const { data: result } = await partnersApi.sendPartnerNotificationTestEvent({
  partnerId,
  idempotencyKey: randomUUID(),
  partnerNotificationTestEventRequest: { eventType: 'invoice.paid' },
});

// delivered: true when your receiver answered with a 2xx status
console.log(result.delivered, result.statusCode, result.durationMs, result.error);

200

{
  "success": true,
  "data": {
    "delivered": true,
    "statusCode": 200,
    "durationMs": 182
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key · string · required

Required: a call without it is refused with 400. A key of your own that names this one request; a UUID is ideal. It is 8 to 50 characters of letters, digits, - and _. Send the same key again when you retry (after a timeout, a dropped connection or a 5xx) and the call is carried out once: the retry gets the first answer back, marked X-Idempotency-Cached: true. The same key with a different body is refused with 422, and a retry that arrives while the first call is still running with 409 (see Retry-After).

Required string length: 8 - 50

Pattern: ^[a-zA-Z0-9_-]{8,50}$

Example:

"9b2d6f0a-3c41-4e5a-8d77-1f2e3a4b5c6d"

Path Parameters

partnerId · string<uuid> · required

The partner whose webhook to try

Body

application/json

Which kind of event to send a sample of.

eventType · enum<string> · required

What happened. The event types you can be told about.

Available options: invoice.issued, invoice.due_soon, invoice.overdue, invoice.paid, invoice.failed, credits.low, credits.managed_user_cap_reached, partner.activated, partner.paused, partner.resumed, storage.check_failed, composition.created, composition.updated, widget.published, upload.created, entry.created, workflow.created, workflow.published, workflow.state_changed, workflow.deleted

Response

200

application/json

The test call was made. delivered says whether your receiver took it.

success · boolean · required

Always true on a success.

Example:

true

data · object · required

How a test call went. The call was made whether or not your receiver took it: read delivered.

Show child attributes

Example:

{
  "delivered": true,
  "statusCode": 42,
  "durationMs": 42,
  "error": "Example error"
}

meta · object

Extra information about the answer: where a page sits in a list, the cursor of the next page, or warnings about a call that succeeded with a caveat.

Show child attributes