BOOK A DEMO

Integrations

Managing Webhooks

Subscribe to events, inspect deliveries, and retry failures — all through the Management API. A webhook subscription is called an Action Hook.

The Webhooks reference describes the payloads Basta sends. This page covers the other half: how to subscribe to those events, inspect deliveries, and retry failures — all through the Management API.

In the API, a webhook subscription is called an Action Hook. When a subscribed event occurs, Basta sends an HTTP POST to the URL you registered.

How it works

  1. You subscribe a URL to one or more event types
  2. When a matching event happens, Basta delivers a POST to that URL
  3. Each delivery is recorded in a log you can inspect
  4. Failed deliveries are retried automatically, and can also be retried manually

Every delivery carries an idempotencyKey so your receiver can safely deduplicate retries. See Webhooks → Base Structure.

Subscribing to an event

GraphQL
mutation AddActionHook {
  addActionHookSubscription(accountId: "ACCOUNT_ID", input: {
    action: BID_ON_ITEM
    url: "https://your-server.example.com/basta/webhooks"
    headers: [
      { name: "X-Webhook-Secret", value: "YOUR_SHARED_SECRET" }
    ]
  }) {
    id
    action
    url
  }
}
  • action — the event type to subscribe to (see the list below)
  • url — your receiving endpoint (must be a valid, reachable HTTPS URL)
  • headers — optional custom headers sent with every delivery, useful for authenticating the request on your side

Subscribe one Action Hook per event type. Use the returned id to update or delete the subscription later.

Available event types

CategoryEvent Types
BiddingBID_ON_ITEM, CANCEL_BID_ON_ITEM, BID_USER_ID_CHANGED
ItemsITEM_ADDED_TO_SALE, SALE_ITEM_UPDATED, SALE_ITEM_REMOVED, ITEMS_STATUS_CHANGED
SalesSALE_CREATED, SALE_UPDATED, SALE_STATUS_CHANGED
OrdersORDER_CREATED, ORDER_UPDATED, ORDER_CANCELLED
RegistrationsSALE_REGISTRATION_CREATED, SALE_REGISTRATION_UPDATED, SALE_REGISTRATION_DELETED, SALE_ITEM_REGISTRATION_CREATED, SALE_ITEM_REGISTRATION_DELETED
WatchlistSALE_WATCHLIST_ENTRY_CREATED, SALE_WATCHLIST_ENTRY_DELETED, SALE_ITEM_WATCHLIST_ENTRY_CREATED, SALE_ITEM_WATCHLIST_ENTRY_DELETED
UsersUSER_UPDATED

The OrderDeleted payload type in the Webhooks reference is not currently available as an Action Hook subscription — orders emit ORDER_CANCELLED rather than a delete event. Marketplace events are not yet delivered via Action Hooks.

Managing subscriptions

OperationPurpose
actionHookSubscriptionsList all subscriptions for the account
addActionHookSubscriptionSubscribe a URL to an event type
updateActionHookSubscriptionChange the URL or headers of a subscription
deleteActionHookSubscriptionRemove a subscription
testActionHookSend a test delivery to validate your endpoint
actionHookLogsInspect delivery history
retryActionHookManually re-send a failed delivery

Testing your endpoint

Before going live, send a test delivery and inspect exactly what your server will receive:

GraphQL
mutation TestHook {
  testActionHook(accountId: "ACCOUNT_ID", input: {
    action: BID_ON_ITEM
    url: "https://your-server.example.com/basta/webhooks"
  }) {
    statusCode
    requestMethod
    requestPayload
    responseBody
  }
}

Delivery logs & retries

Each delivery attempt is logged with its status, response, and retry count, so you can diagnose integration issues.

Delivery StatusMeaning
PENDINGQueued to be sent
SUCCESSDelivered successfully
FAILEDDelivery failed
RETRYScheduled for an automatic retry
GraphQL
query ActionHookLogs {
  actionHookLogs(
    accountId: "ACCOUNT_ID"
    first: 20
    filter: { statuses: [FAILED, RETRY] }
  ) {
    edges {
      node {
        id
        action
        url
        status
        retries
        error
        executedAt
        nextRetryDate
      }
    }
  }
}

To re-send a specific failed delivery:

GraphQL
mutation Retry {
  retryActionHook(accountId: "ACCOUNT_ID", input: { id: "LOG_ID" }) {
    id
    status
  }
}

Best practices

  1. Verify deliveries — use a custom header (e.g. a shared secret) to confirm requests came from Basta
  2. Deduplicate — key on idempotencyKey so retries don't double-process
  3. Respond quickly — acknowledge with a 2xx and do heavy work asynchronously
  4. Monitor logs — periodically review FAILED deliveries and alert on sustained failures

Related documentation

Questions about webhook delivery? Contact us at hi@basta.app