Test and Debug Webhooks

Simulate events and provider failures, inspect delivery logs, and replay stored events from the Dashboard.

Use a Mock account to test events and failure scenarios without contacting real people. Use an endpoint's delivery log to inspect what Unipile sent and how your receiver responded.

Set up a testing account

  1. Open a Development application and select Testing. Testing mode is not available in Production.
  2. If no test account is linked, use the connection button to link a Mock account.
  3. Register a webhook endpoint in the same application, allowing that account and the event types you want to test.

Linking a Mock account emits account.add. The account is ready immediately; do not wait for account.status.running on creation. You can call supported Methods against its ID to receive simulated data.

Trigger a test event

In the Webhooks section of the Testing screen, select an event type and click Trigger event. The event is sent with mock data through the application's configured webhook endpoints.

By default the payload contains only required fields. Enable Fill optional fields to include optional fields as well. Test both variants to check your application handles missing optional data.

Simulate provider behavior

The Testing screen's Provider behaviors section offers:

  • Simulate session expiration / access revoking: puts the account into an authentication-required state. Use its authentication action to reconnect it and exercise your recovery experience.
  • Simulate provider outage: puts the account into a service-interruption state.
  • End provider outage: restores the simulated provider after an outage.

Watch the account status and your webhook receiver after each action. See Connection Status for which events and recovery actions correspond to those transitions.

Open an endpoint's delivery log

Open Webhooks and select an endpoint. Its detail page shows the endpoint configuration, enabled status, subscribed events, account targets, and signing secret. Reveal and copy the secret when configuring signature verification.

The delivery log lists attempts with the newest first. You can refresh it and load more entries. On a small screen, use Deliveries and Event details to switch between the list and selected attempt.

Webhook event and delivery data is retained for seven days. Collect information needed for your own longer-term diagnosis in your receiver's logs.

Search and filter deliveries

  • Enter a complete event ID (evt_…) or account ID (acc_…) in the search box. It does not support arbitrary full-text searches.
  • Filter by event type, Succeeded or Failed, account, or date range.
  • Select one date for a single day, or two dates for an inclusive range. The picker is limited to the retention window.
  • Use Clear filters to reset the dropdown and date filters; clear the search separately.

Filters combine to narrow the results. If an account ID is entered in the search box, it takes precedence over the account dropdown. The account dropdown includes accounts whose events were delivered to this endpoint, including retained entries for deleted accounts.

If no results appear, check the ID, filters, retention period, endpoint account selection, and subscribed event types.

Inspect an attempt

Select a delivery to inspect:

DetailMeaning
Event detailsType, creation date, event ID, account, and Scope when present.
Endpoint responseDestination URL, response body when available, and timing measurements.
LatencyTime between the event occurring and Unipile starting delivery to the endpoint.
Response timeTime taken by the endpoint to respond, including the full timeout for timed-out requests.
Delivery attemptsAttempts associated with the event at this endpoint, including automatic retries.
Event dataThe event's payload.
RawThe complete event object displayed as JSON.

A successful delivery has an HTTP 2xx response. An attempt with no HTTP response needs investigation separately from an HTTP error returned by the receiver. Displayed JSON is useful for inspection; signature verification must use the exact raw bytes received by your webhook handler.

Unipile expects a successful response within five seconds and retries failed delivery after two seconds and then twelve seconds. See Configure a webhook for receiver implementation.

Replay an event

For a stored event, you can queue another delivery even after an earlier success:

  1. Open the event in the endpoint's log.
  2. Choose Replay This Endpoint to resend to this original endpoint.
  3. Alternatively, open More replay actions and choose Replay to All Eligible Endpoints.
  4. Wait for the new attempts and inspect their responses.

Eligible endpoints are currently enabled and match the event type and account. Replay uses the original event ID and payload, but the current endpoint URL and signing secret. It follows the normal retry behavior and runs asynchronously: a queued confirmation is not proof that the receiver accepted it.

Your receiver must handle duplicate event IDs safely. Replaying a successfully processed event can trigger the same business operation again if your handler does not deduplicate it. Events removed after retention cannot be replayed. See Replay a Webhook Event for the API equivalent.

Change or pause an endpoint

Open its actions menu to modify the URL, description, account targets, or event subscriptions. Save the form after editing.

Choose Disable and confirm to pause the endpoint, or Enable to activate it again. Choose Delete and confirm to remove it permanently. Changing or deleting an endpoint follows application permissions: Members can do so in Development; Admins and Owners can do so in Production as well.

Diagnose missing events

First determine whether an event was created and attempted, whether the receiver rejected it, or whether provider connectivity prevented the event from being received. Check the endpoint's enabled state, event selection, account targets, account status, and subscription access. See Troubleshoot Connection Issues for provider failures.


Did this page help you?