Choose where your notifications go

Changes who gets the emails, which events you want by email and by webhook, and the address of your webhook. A key you leave out of the body is left as it was; send only what changes.

Email. emailRecipients is the list of addresses (at most five). While it is empty the emails about invoices go to the billing emails of your billing profile (your contact email when there are none), and the others to your contact email. The events about money and about the standing of your account are always emailed, whatever emailEvents says; it narrows the others.

Webhook. webhookUrl is where Widgetic sends a signed POST for each event, so that your own system can act on it (mark an invoice paid, warn your team that credits are low). The address must be https on the standard port, on a public site, and must not redirect. Setting an address when you have no secret yet makes one, and the answer carries it as webhookSecret: keep it now, it is shown once. webhookEvents narrows what is sent.

Each call has a JSON body, { "id": "evt_...", "type": "invoice.paid", "createdAt": "...", "partnerId": "...", "data": { ... } } (data is the data of PartnerNotification), and these headers: webhook-id (the same as id, and the same on every retry), webhook-timestamp (seconds since 1970) and webhook-signature (v1, and a base64 HMAC-SHA256). It is the Standard Webhooks scheme, so any of its libraries verifies it. By hand: take your secret without the whsec_ prefix, decode it from base64, and sign the text <webhook-id>.<webhook-timestamp>.<the raw body> with it; the header holds v1,<base64 of the result> (two signatures separated by a space while a rotated secret overlaps). Reject a webhook-timestamp that is more than five minutes old.

Answer with a 2xx status within ten seconds. Anything else is tried again, eight attempts in all over about two days (listPartnerNotificationDeliveries shows each). Delivery is at least once: if your answer was lost the same event arrives again with the same id, so drop what you have already handled by it.

Changing the settings needs an API key with full access: they decide where your notifications go. The caller must be the person who administers the partner, or a Widgetic administrator.

PUT /partners/{partnerId}/notifications/settings

TypeScript SDK

TypeScript

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

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

// Send every payment event to your own system:
const { data: change } = await partnersApi.updatePartnerNotificationSettings({
  partnerId,
  updatePartnerNotificationSettingsRequest: {
    webhookUrl: 'https://example.com/widgetic/events',
    webhookEvents: ['invoice.issued', 'invoice.paid', 'invoice.failed']
  }
});

// Shown once: put it in your receiver's configuration now.
console.log(change.webhookSecret);

200

{
  "success": true,
  "data": {
    "settings": null,
    "webhookSecret": "Example webhookSecret"
  },
  "meta": {
    "page": 1,
    "size": 20,
    "total": 135,
    "limit": 20,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "<string>",
    "warnings": [
      "<string>"
    ]
  }
}

Authorizations

Authorization · string · header · required

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

Headers

Idempotency-Key · string

Optional: without it the call is carried out every time it is sent. 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 notification settings to change

Body

application/json

What to change. A key you leave out is left as it was.

emailRecipients · string[]

The addresses the emails go to, at most five. An empty list goes back to the defaults.

Maximum array length: 5

emailEvents · enum<string>[] | null

The events you want by email. Null for every event.

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

webhookEvents · enum<string>[] | null

The events to send to your webhook. Null for every event.

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

webhookUrl · string | null

Where to send the signed calls. It must be an https address on the standard port, on a public site, and it must not redirect. Null or an empty text switches the webhook off. Setting an address when you have no secret yet makes one.

Maximum string length: 2000

Response

200

application/json

The settings were saved

success · boolean · required

Always true on a success.

Example:

true

data · object · required

The settings after a change, and the new signing secret when one was made.

Show child attributes

Example:

{
  "settings": null,
  "webhookSecret": "Example webhookSecret"
}

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