Skip to main content
Yoshi provides several ways to test your webhook integration before going to production.

​
Send a test event

Every endpoint has a test action that sends a synthetic test.ping event. Use it to verify your handler is reachable and responding correctly: 
curl -X POST https://api.yoshi.ai/v1/webhooks/endpoints/{endpoint_id}/test \
  -H "Authorization: Bearer yoshi_3xK9mP..."

{
  "data": {
    "sent": true,
    "event_id": "evt_test_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "meta": {
    "request_id": "req_a1b2c3d4",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}
Your endpoint will receive a webhook with this payload: 
{
  "id": "evt_test_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "test.ping",
  "created_at": "2026-04-10T12:00:00.000Z",
  "api_version": "2026-04-10",
  "data": {
    "test": true,
    "message": "This is a test webhook from Yoshi."
  }
}
The test.ping event type is synthetic — it’s only sent when you explicitly trigger a test. It won’t appear in your event subscriptions or filter settings.

​
Test locally

To receive webhooks on your local machine during development, expose your local server to the internet using a tunnel.

​
Using ngrok

1

Start your local server

Run your webhook handler on a local port (e.g., http://localhost:3000).
2

Start ngrok

ngrok http 3000
ngrok outputs a public URL like https://a1b2c3d4.ngrok-free.app.
3

Register the tunnel URL as an endpoint

curl -X POST https://api.yoshi.ai/v1/webhooks/endpoints \
  -H "Authorization: Bearer yoshi_3xK9mP..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://a1b2c3d4.ngrok-free.app/webhooks/yoshi",
    "description": "Local development"
  }'
Save the secret from the response — you’ll need it for signature verification.
4

Send a test event

curl -X POST https://api.yoshi.ai/v1/webhooks/endpoints/{endpoint_id}/test \
  -H "Authorization: Bearer yoshi_3xK9mP..."
You should see the test.ping event arrive in your local server logs.

​
Using webhook.site

If you just want to inspect webhook payloads without building a handler:
  1. Go to webhook.site to get a temporary URL.
  2. Register it as a webhook endpoint via the API.
  3. Send a test event or wait for real events to arrive.
  4. Inspect the full request headers and body on the webhook.site dashboard.
This is useful for verifying that events are being sent and payloads look correct before writing handler code.

​
Inspect delivery logs

View recent delivery attempts via the API: 
curl https://api.yoshi.ai/v1/webhooks/deliveries \
  -H "Authorization: Bearer yoshi_3xK9mP..."

{
  "data": {
    "deliveries": [
      {
        "id": "d1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "event_type": "transaction.created",
        "event_id": "msg_a1b2c3d4",
        "status": "delivered",
        "created_at": "2026-04-10T14:30:00.000Z"
      }
    ]
  },
  "has_more": false,
  "cursor": null,
  "count": 1,
  "meta": {
    "request_id": "req_a1b2c3d4",
    "timestamp": "2026-04-10T15:00:00.000Z"
  }
}
The status field is one of:
StatusDescription
deliveredYour endpoint returned 2xx.
pendingDelivery is in progress or queued for retry.
failedAll delivery attempts were exhausted.
For more detailed logs, use the consumer portal which shows full request/response details for each delivery attempt.

​
Replay failed events

If deliveries fail due to a temporary issue on your end (e.g., a deploy that caused downtime), you can replay them from the consumer portal:
  1. Open the portal via GET /v1/webhooks/portal.
  2. Navigate to the failed deliveries.
  3. Click Replay to resend individual events or replay all failed events for a time range.

​
Debugging checklist

If webhooks aren’t arriving at your endpoint:
Your endpoint must be publicly accessible over HTTPS. Local URLs like http://localhost:3000 won’t work — use a tunnel like ngrok for local development.
Check GET /v1/webhooks/deliveries for the HTTP status code your endpoint returned. Non-2xx responses trigger retries.
If your handler takes too long, the delivery times out and is retried. Return 200 immediately and process the event in the background.
Check GET /v1/webhooks/endpoints to verify the endpoint’s status is active. Endpoints are automatically disabled after repeated failures.
If you set filter_types when creating the endpoint, only those event types will be delivered. An empty filter_types array receives all events.
If your handler rejects the signature, double-check that you’re using the raw request body (not a parsed-then-serialized version) and the correct signing secret.
Last modified on April 17, 2026