# Send a test event to any URL

HTML: https://www.app2email.com/docs/api/webhooks/test-webhook-url · Index: https://www.app2email.com/docs/api/llms.txt

`POST https://api.app2email.com/v1/{number}/webhooks/test-url` · scope `webhooks:manage` · MCP tool `test_webhook_url`

One signed POST to any https URL, answered with the exact request sent and your URL's answer. No saved webhook needed. Shares the 30 tests an hour of the number (429 too_many_tests with Retry-After); 60 an hour per target host and per its IP address.

```shell
curl -X POST "https://api.app2email.com/v1/YOUR_NUMBER/webhooks/test-url" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://hooks.example.com/app2email",
  "type": "ping"
}'
```

## OpenAPI

```json
{
  "/v1/{number}/webhooks/test-url": {
    "post": {
      "tags": [
        "Webhooks"
      ],
      "operationId": "testWebhookUrl",
      "summary": "Send a test event to any URL",
      "description": "One signed POST to any https URL, answered with the exact request sent and your URL's answer. No saved webhook needed. Shares the 30 tests an hour of the number (429 too_many_tests with Retry-After); 60 an hour per target host and per its IP address.",
      "parameters": [
        {
          "$ref": "#/components/parameters/Number"
        }
      ],
      "requestBody": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WebhookTestUrlRequest"
            },
            "example": {
              "url": "https://hooks.example.com/app2email",
              "type": "ping"
            }
          }
        }
      },
      "responses": {
        "200": {
          "description": "The test was made: see result.ok and result.stage.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookTestUrlResponse"
              },
              "examples": {
                "answered": {
                  "summary": "Your URL answered 200",
                  "value": {
                    "success": true,
                    "request_id": "t7kq2",
                    "sent": {
                      "method": "POST",
                      "url": "https://hooks.example.com/app2email",
                      "headers": {
                        "Content-Type": "application/json; charset=utf-8",
                        "User-Agent": "app2email-webhooks/1.0",
                        "X-App2email-Event": "ping",
                        "X-App2email-Delivery": "evt_Xq3k9m2Lw8Rt5Yp1Zs01",
                        "X-App2email-Signature": "t=1762390800,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd",
                        "X-Hub-Signature-256": "sha256=7d0e8a4a2a5c0b8b1a8f3f62c1d0e2b5c6f8a9e0d1c2b3a4f5e6d7c8b9a0f1e2",
                        "X-App2email-Test": "true"
                      },
                      "body": "{\"id\":\"evt_Xq3k9m2Lw8Rt5Yp1Zs01\",\"type\":\"ping\",\"created\":\"2026-11-06T01:00:00.000Z\",\"number\":\"4976659348270\",\"test\":true,\"data\":{\"webhook_id\":\"wh_test_url\",\"message\":\"Test event. If you can see this, your webhook works.\"}}",
                      "secret": "whsec_3Fq9LmZ2xT8pW1rK7vB4nD6sH0jC5yA9",
                      "secret_generated": true
                    },
                    "result": {
                      "ok": true,
                      "stage": "response",
                      "status": 200,
                      "ms": 184,
                      "headers": {
                        "Content-Type": "application/json",
                        "Date": "Fri, 06 Nov 2026 01:00:00 GMT",
                        "Server": "nginx"
                      },
                      "body": "{\"received\":true}",
                      "body_truncated": false
                    }
                  }
                },
                "dns": {
                  "summary": "The host name does not resolve",
                  "value": {
                    "success": true,
                    "request_id": "t7kq3",
                    "sent": {
                      "method": "POST",
                      "url": "https://hooks.example.invalid/app2email",
                      "headers": {
                        "Content-Type": "application/json; charset=utf-8",
                        "User-Agent": "app2email-webhooks/1.0",
                        "X-App2email-Event": "ping",
                        "X-App2email-Delivery": "evt_Xq3k9m2Lw8Rt5Yp1Zs01",
                        "X-App2email-Signature": "t=1762390800,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd",
                        "X-Hub-Signature-256": "sha256=7d0e8a4a2a5c0b8b1a8f3f62c1d0e2b5c6f8a9e0d1c2b3a4f5e6d7c8b9a0f1e2",
                        "X-App2email-Test": "true"
                      },
                      "body": "{\"id\":\"evt_Xq3k9m2Lw8Rt5Yp1Zs01\",\"type\":\"ping\",\"created\":\"2026-11-06T01:00:00.000Z\",\"number\":\"4976659348270\",\"test\":true,\"data\":{\"webhook_id\":\"wh_test_url\",\"message\":\"Test event. If you can see this, your webhook works.\"}}",
                      "secret": "whsec_3Fq9LmZ2xT8pW1rK7vB4nD6sH0jC5yA9",
                      "secret_generated": true
                    },
                    "result": {
                      "ok": false,
                      "stage": "dns",
                      "ms": 0,
                      "message": "the host name hooks.example.invalid does not resolve"
                    }
                  }
                }
              }
            }
          }
        },
        "400": {
          "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "401": {
          "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "403": {
          "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "404": {
          "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "413": {
          "description": "The request or the media file is too large. Possible error.code values: request_too_large, media_too_large, approval_body_too_large, test_event_too_large, flow_json_too_large.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "429": {
          "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "500": {
          "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        }
      },
      "x-a2e-scope": "webhooks:manage",
      "x-a2e-sandbox": "live",
      "x-a2e-error-codes": [
        "api_key_expired",
        "api_key_number_mismatch",
        "api_key_old_format",
        "api_key_revoked",
        "insufficient_scope",
        "internal_error",
        "invalid_api_key",
        "invalid_authorization_header",
        "invalid_events",
        "invalid_json",
        "invalid_number_in_url",
        "invalid_test_event",
        "invalid_webhook_format",
        "invalid_webhook_headers",
        "invalid_webhook_secret",
        "invalid_webhook_url",
        "ip_not_allowed",
        "missing_api_key",
        "missing_url",
        "number_not_found",
        "plan_not_allowed",
        "rate_limited",
        "service_not_live",
        "test_event_too_large",
        "too_many_tests"
      ],
      "x-a2e-webhook-events": [],
      "x-a2e-mcp-tool": "test_webhook_url",
      "x-a2e-needs": null
    }
  }
}
```
