# Change a webhook: url, active, headers, format

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

`PATCH https://api.app2email.com/v1/{number}/webhooks/{id}` · scope `webhooks:manage` · MCP tool `update_webhook`

Only what is given changes: url, active, headers (a header set to null is removed), format. `active: true` turns a webhook back on after it was switched off for failures (and clears the failure count). The same url as another webhook of the number: 409 webhook_url_in_use. Needs the 'webhooks:manage' scope.

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

## OpenAPI

```json
{
  "/v1/{number}/webhooks/{id}": {
    "patch": {
      "tags": [
        "Webhooks"
      ],
      "operationId": "updateWebhook",
      "summary": "Change a webhook: url, active, headers, format",
      "description": "Only what is given changes: url, active, headers (a header set to null is removed), format. `active: true` turns a webhook back on after it was switched off for failures (and clears the failure count). The same url as another webhook of the number: 409 webhook_url_in_use. Needs the 'webhooks:manage' scope.",
      "parameters": [
        {
          "$ref": "#/components/parameters/Number"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "The webhook's id.",
          "schema": {
            "type": "string",
            "example": "wh_a1b2c3d4e5f6g7h8"
          }
        }
      ],
      "requestBody": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WebhookPatchRequest"
            },
            "example": {
              "url": "https://hooks.example.com/app2email",
              "active": true
            }
          }
        }
      },
      "responses": {
        "200": {
          "description": "The webhook.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookResponse"
              },
              "example": {
                "success": true,
                "request_id": "v3gkx",
                "webhook": {
                  "id": "wh_a1b2c3d4e5f6g7h8",
                  "url": "https://hooks.example.com/app2email",
                  "events": [
                    "message.status",
                    "message.received",
                    "message.failed",
                    "contact.opted_out",
                    "broadcast.completed",
                    "usage.threshold",
                    "template.status_changed",
                    "conversation.owner_changed",
                    "message.held_for_approval",
                    "approval.resolved",
                    "contact.updated",
                    "waitlist.joined",
                    "waitlist.notified",
                    "waitlist.removed",
                    "booking.created",
                    "booking.cancelled",
                    "booking.rescheduled",
                    "booking.rated",
                    "flow.completed",
                    "booking.updated",
                    "booking.note.created",
                    "calendar.block.created",
                    "calendar.block.deleted",
                    "call.incoming",
                    "call.status",
                    "message.edited",
                    "message.deleted",
                    "contact.changed_number",
                    "number.updated",
                    "number.error",
                    "flow.status_changed",
                    "booking.paid",
                    "booking.refunded",
                    "payment.paid",
                    "package.purchased",
                    "poll.voted",
                    "poll.closed",
                    "booking.customer.erased",
                    "order.created",
                    "order.paid",
                    "order.accepted",
                    "order.ready",
                    "order.completed",
                    "order.cancelled",
                    "order.refunded",
                    "order.no_show",
                    "submission.created",
                    "submission.files_ready",
                    "submission.updated",
                    "submission.status_changed",
                    "submission.assigned",
                    "submission.note_added",
                    "submission.customer_replied",
                    "submission.deleted",
                    "submit.automation_failed",
                    "ticket.order.confirmed",
                    "ticket.order.refunded",
                    "ticket.checked_in",
                    "ticket.passed_on",
                    "ticket.event.sold_out",
                    "ticket.event.cancelled",
                    "ticket.waitlist.joined",
                    "ticket.buyer.erased"
                  ],
                  "secret": "whsec_...",
                  "created": "2026-10-20T04:00:00Z",
                  "active": true,
                  "disabled_reason": null,
                  "last_delivery": {
                    "at": "2026-10-26T01:12:11Z",
                    "ok": true,
                    "result": "200"
                  }
                }
              }
            }
          }
        },
        "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"
              }
            }
          }
        },
        "409": {
          "description": "Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published. Possible error.code values: idempotency_request_in_progress, idempotency_request_interrupted, template_already_exists, broadcast_not_cancellable, broadcast_cancelled, webhook_url_in_use, approval_already_resolved, approval_expired, segment_exists, number_already_verified, username_taken, number_not_live, key_limit_reached, key_limits_unavailable, plan_not_available, plan_already_active, waitlist_not_set_up, waitlist_not_offered, booking_slot_taken, booking_cancelled, hold_expired, slug_taken, flow_not_editable, flow_not_published, flow_not_deletable, flow_name_taken, encryption_key_managed, username_not_available, client_exists, payments_not_connected, refund_not_possible, too_late, shop_not_tracked, shop_sku_taken, shop_limit, shop_changed, shop_order_problems, form_not_published, form_has_submissions, form_exists, connection_in_use, stage_not_allowed, template_not_editable, template_category_locked, template_insights_not_enabled, tickets_not_on_sale, tickets_sold_out, ticket_seat_not_available, ticket_limit_reached, ticket_not_allowed, ticket_event_not_publishable, delivery_in_progress.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "422": {
          "description": "The request is understood but cannot be sent (template parameters, media, text, recipient, or a WhatsApp rule such as the 24 hour window). Possible error.code values: template_not_approved, template_parameters_invalid, invalid_base64, invalid_media_link, media_download_failed, media_type_not_allowed, recipient_not_allowed, recipient_unreachable, template_parameter_count_mismatch, template_text_too_long, template_format_policy, template_parameter_format_mismatch, template_paused, template_disabled, template_parameter_invalid, required_parameter_missing, parameter_value_invalid, media_download_error, media_upload_error, idempotency_key_reused, invalid_webhook_url, outside_24h_window, text_too_long, caption_too_long, invalid_email, template_rejected, bsuid_not_supported, marketing_per_user_limit, recipient_in_experiment, template_not_marketing, recipient_is_sender, whatsapp_parameter_error, block_users_failed, block_list_full, username_change_limit, sandbox_recipient, flow_cannot_publish, flow_rejected, reaction_too_old, message_too_old, voice_needs_ogg_opus, marketing_disabled_on_cloud_api, recipient_identity_changed, username_account_not_linked, template_limit_reached, template_insights_unavailable, template_archive_failed, template_unarchive_failed, template_compare_unavailable.",
          "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_json",
        "invalid_number_in_url",
        "invalid_webhook_format",
        "invalid_webhook_headers",
        "invalid_webhook_url",
        "ip_not_allowed",
        "missing_api_key",
        "nothing_to_change",
        "number_not_found",
        "plan_not_allowed",
        "rate_limited",
        "service_not_live",
        "webhook_not_found",
        "webhook_url_in_use"
      ],
      "x-a2e-webhook-events": [],
      "x-a2e-mcp-tool": "update_webhook",
      "x-a2e-needs": null
    }
  }
}
```
