Integrations
Send your store's sale, payment, and redelivery events to your own server with webhooks, and find where API keys live.
The Integrations page connects your store to software that you or your developer run outside Allomancy. It has two tabs: Webhooks, which sends your store's sale, payment, and redelivery events to your own server as they happen, and API Keys, which holds the keys a developer uses to call the Developer API.
Webhooks are separate from Discord notifications, which post sale messages to a Discord channel.
Adding a webhook
To send events to your server, open the Webhooks tab, click Add Webhook, and fill in the dialog:
- Name: a name to tell your webhooks apart.
- Destination URL: the address of your server. It needs a host name, not an IP address; see Hosting on a small server if your server has only an IP address.
- Events: the events to send.
sale.completedis sent when a sale completes at one of your vendors,payment.receivedwhen a payment terminal receives L$, andmarketplace.sale.completedwhen a sale completes on the Second Life Marketplace.redelivery.completedis sent when a redelivery of one of your products to a customer is recorded, such as one a customer requests on your customer page. A mass redelivery or a product you deliver yourself does not send it.marketplace.redelivery.completedis sent when a Second Life Marketplace redelivery is recorded. Events lists exactly what each one covers. - Signing secret: every delivery is signed with this secret, so your server can check that it came from Allomancy. Click Generate to create one, or paste your own
whsec_secret.
Before you save, click Copy next to a generated secret and give it to whoever runs your server, because a saved secret cannot be shown again. Then click Add Webhook.
A store can have up to 3 active webhooks, and each active webhook needs its own name.
A URL that starts with http:// is accepted, but the payloads, including sale details and residents' names, can be read in transit. The webhooks list marks such a webhook with an HTTP badge. Use https:// when you can.
Checking that a webhook works
To send a test event, click on the webhook's row and choose Send Test. You can send one test per webhook per minute, and a test also reaches a webhook that is disabled.
A test that fails is not listed under Delivery Failures, so check what your server received and logged. Verifying a webhook shows how a server checks each delivery.
Changing a webhook
To change a webhook's name, URL, events, or signing secret, click on its row. Leave Signing secret empty to keep the current secret. Saving changes neither the webhook's status nor its failure count.
When you replace the secret, deliveries that were already queued keep the old one; see Signing secrets and rotation for how to switch your server over.
Pausing, resuming, and deleting a webhook
Each of these is in the menu on the webhook's row:
- Disable stops deliveries to an active webhook and keeps the webhook and its history.
- Enable turns a disabled webhook back on and resets its failure counter. It needs a free active slot and a name that no other active webhook uses.
- Delete removes the webhook and its delivery failures. This cannot be undone.
What happens to events from the time a webhook was disabled is covered under Enable a subscription.
When a webhook is disabled after failures
The Status column shows Active, Disabled, or Disabled after failures. A webhook is disabled after failures when 10 events in a row end in a delivery failure. Its row then shows the number of consecutive failures and when it was disabled, and Allomancy tries once to tell you in an inworld IM.
To resume deliveries, fix your server and choose Enable. To see what went wrong for that webhook, choose View Failures in its menu.
Reviewing delivery failures
To see the events that could not be delivered, click Delivery Failures above the webhooks list. Failures are kept for 30 days.
Each row shows the Time, the Webhook, the Event, the kind of Failure, the HTTP Status your server answered with (No response when it did not answer), the number of Attempts, and the Error.
| Failure | What happened | What to check |
|---|---|---|
| HTTP error | Your server answered with an error status or a redirect. | The HTTP Status and Error columns. Redirects are not followed, so use the final address, not one that redirects. |
| Timed out | Your server did not answer in time. | Your server answers quickly: it checks the delivery, stores the event, and answers before doing any slow work. |
| Network error | A connection could not be completed, or the host name could not be found. | Your server is running and reachable, and its host name resolves. |
| Rejected before sending | The URL, its destination, or the signing secret was not allowed. | The Error column says which. The URL must meet the destination URL requirements. |
For what each status means, including the ones Cloudflare answers with when it cannot reach your server, see Delivery failures.
API keys
The API Keys tab holds the keys a developer uses to call the Developer API. To create one, see Get an API key; to edit or revoke one, see The key lifecycle.
Permissions
Integrations is available only to the store owner. Store managers do not see it in the sidebar, whatever their permissions. See Store Managers for the other owner-only areas.