---
title: "Send test webhook event"
description: "Sends one signed sample event to this endpoint through its normal queue, ignoring its event-type and RFC filters. The issuer must belong to the workspace. Example IDs do not resolve to real documents. Disabled endpoints cannot receive test events. Identical retries return the original delivery."
language: en
canonical_url: "https://exac.mx/docs/en/api/workspace/credentials/test-webhook-endpoint"
md_url: "https://exac.mx/docs/en/api/workspace/credentials/test-webhook-endpoint.md"
---

# Send test webhook event

Sends one signed sample event to this endpoint through its normal queue, ignoring its event-type and RFC filters. The issuer must belong to the workspace. Example IDs do not resolve to real documents. Disabled endpoints cannot receive test events. Identical retries return the original delivery.

## Request

`POST /v1/organization/webhook-endpoints/{endpointId}/test`

- **Authorization:** Required permission: `apiKeys:manage`.

- **Environments:** Production and sandbox

- **Idempotency:** Required

## Canonical machine contract

This fragment is generated from the canonical operation and Zod contracts used by the route.

```json
{
  "method": "POST",
  "path": "/v1/organization/webhook-endpoints/{endpointId}/test",
  "operation": {
    "operationId": "testWebhookEndpoint",
    "tags": [
      "Credentials"
    ],
    "summary": "Send test webhook event",
    "description": "Sends one signed sample event to this endpoint through its normal queue, ignoring its event-type and RFC filters. The issuer must belong to the workspace. Example IDs do not resolve to real documents. Disabled endpoints cannot receive test events. Identical retries return the original delivery.",
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "parameters": [
      {
        "name": "endpointId",
        "in": "path",
        "required": true,
        "example": "example_endpoint_id",
        "schema": {
          "type": "string",
          "minLength": 1
        }
      },
      {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "example": "2f6b0e7a-5c1d-4e3a-9b8f-7d4a1c9e6b52",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "description": "Unique retry key for this exact operation. Reuse it only when retrying the same request."
      }
    ],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "eventType": {
                "anyOf": [
                  {
                    "type": "string",
                    "const": "invoice.stamped"
                  },
                  {
                    "type": "string",
                    "const": "invoice.canceled"
                  },
                  {
                    "type": "string",
                    "const": "sat_sync.completed"
                  }
                ]
              },
              "issuer": {
                "type": "string",
                "minLength": 1
              }
            },
            "required": [
              "eventType",
              "issuer"
            ],
            "additionalProperties": false
          },
          "example": {
            "eventType": "invoice.stamped",
            "issuer": "AAA010101AAA"
          }
        }
      }
    },
    "responses": {
      "201": {
        "description": "Operation completed.",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "data": {
                  "$ref": "#/components/schemas/WebhookDelivery"
                }
              },
              "required": [
                "data"
              ],
              "additionalProperties": false
            }
          }
        }
      },
      "400": {
        "description": "Invalid request.\n\n`validation_error`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "401": {
        "description": "Missing or invalid credential.\n\n`unauthenticated`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "WWW-Authenticate": {
            "$ref": "#/components/headers/WWWAuthenticate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "402": {
        "description": "Insufficient prepaid balance or an unmet billing requirement.\n\n`payment_required`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "403": {
        "description": "The credential does not include the `apiKeys:manage` permission.\n\n`forbidden`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "WWW-Authenticate": {
            "$ref": "#/components/headers/WWWAuthenticate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "404": {
        "description": "Resource not found.\n\n`not_found`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "405": {
        "description": "Method not allowed.\n\n`method_not_allowed`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Allow": {
            "$ref": "#/components/headers/Allow"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "409": {
        "description": "State, environment, or idempotency conflict. Use error.code to determine recovery.\n\nPossible codes: `conflict`, `idempotency_conflict`, `operation_in_progress`, `recovery_required`, `migration_required`.",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "429": {
        "description": "Too many requests.\n\n`rate_limited`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "500": {
        "description": "Internal server error.\n\n`internal`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      },
      "503": {
        "description": "Service temporarily unavailable.\n\n`provider_unavailable`",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      }
    },
    "x-exac-environments": [
      "production",
      "sandbox"
    ],
    "x-exac-rate-limit": "sensitive"
  },
  "components": {
    "schemas": {
      "ApiError": {
        "type": "object",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ProgrammaticError"
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      },
      "ProgrammaticError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "validation_error",
              "unauthenticated",
              "forbidden",
              "payment_required",
              "not_found",
              "method_not_allowed",
              "conflict",
              "idempotency_conflict",
              "operation_in_progress",
              "recovery_required",
              "migration_required",
              "rate_limited",
              "provider_unavailable",
              "internal"
            ],
            "description": "Recommended action by code:\n\n- `validation_error` — Correct the request using error.message and, when present, details.issues paths and codes.\n- `unauthenticated` — Provide a valid API key or OAuth access token.\n- `forbidden` — Use a credential with the required permission.\n- `payment_required` — For details.reason = api_wallet_insufficient, add prepaid API/MCP credit using details.topUpUrl; balanceMinor is the balance in centavos. Otherwise review the billing requirement. Retry only after it is resolved.\n- `not_found` — Check the organization-scoped resource identifier.\n- `method_not_allowed` — Use the documented HTTP method.\n- `conflict` — Refresh the resource and resolve its current state.\n- `idempotency_conflict` — Use a new idempotency key for a changed request.\n- `operation_in_progress` — Wait for Retry-After, then repeat the exact request.\n- `recovery_required` — Do not retry automatically or change the idempotency key. Retrieve details.document.documentRef when present, verify the outcome, and contact support with Request-Id if it remains uncertain.\n- `migration_required` — Contact support to complete historical document migration; do not reissue the document.\n- `rate_limited` — Wait for Retry-After before retrying.\n- `provider_unavailable` — Retry only when the response marks the failure as retryable.\n- `internal` — A failed response does not prove that a write had no effect. Retry a read after backoff; retry a write only with its original idempotency key and unchanged request. Contact support with Request-Id if it persists."
          },
          "message": {
            "type": "string"
          },
          "details": {
            "type": "object",
            "properties": {
              "document": {
                "type": "object",
                "properties": {
                  "documentRef": {
                    "$ref": "#/components/schemas/DocumentRef"
                  },
                  "editable": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "documentRef",
                  "editable"
                ],
                "additionalProperties": false
              },
              "issues": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "path": {
                      "type": "array",
                      "items": {
                        "anyOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "number"
                          }
                        ]
                      }
                    },
                    "message": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "path",
                    "message"
                  ],
                  "additionalProperties": false
                }
              },
              "retryable": {
                "type": "boolean"
              },
              "retryAfterSeconds": {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 9007199254740991
              },
              "reason": {
                "type": "string"
              },
              "balanceMinor": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "topUpUrl": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "status": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "code",
          "message",
          "status"
        ],
        "additionalProperties": false
      },
      "DocumentRef": {
        "type": "string",
        "pattern": "^(invoice|withholding|sales_receipt|declaration|tax_compliance_opinion|sales_receipt_refund):.+$"
      },
      "WebhookDelivery": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "delivered",
              "failed"
            ]
          },
          "trigger": {
            "type": "string",
            "enum": [
              "event",
              "replay",
              "test"
            ]
          },
          "attempts": {
            "type": "number"
          },
          "nextAttemptAt": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Instant"
              },
              {
                "type": "null"
              }
            ]
          },
          "lastAttempt": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "statusCode": {
                    "anyOf": [
                      {
                        "type": "number"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "failureReason": {
                    "anyOf": [
                      {
                        "type": "string",
                        "enum": [
                          "invalid_url",
                          "blocked_address",
                          "dns",
                          "tls",
                          "timeout",
                          "redirect",
                          "http_error",
                          "connection",
                          "signing"
                        ]
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "durationMs": {
                    "type": "number"
                  },
                  "attemptedAt": {
                    "$ref": "#/components/schemas/Instant"
                  }
                },
                "required": [
                  "statusCode",
                  "failureReason",
                  "durationMs",
                  "attemptedAt"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "createdAt": {
            "$ref": "#/components/schemas/Instant"
          },
          "event": {
            "anyOf": [
              {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "const": "invoice.stamped"
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "invoiceId": {
                            "type": "string"
                          },
                          "uuid": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "income",
                              "credit_note",
                              "transfer",
                              "payroll",
                              "payment_complement"
                            ]
                          },
                          "direction": {
                            "type": "string",
                            "enum": [
                              "issued",
                              "received"
                            ]
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "draft",
                              "valid",
                              "canceled"
                            ]
                          }
                        },
                        "required": [
                          "invoiceId",
                          "uuid",
                          "kind",
                          "direction",
                          "status"
                        ],
                        "additionalProperties": false
                      },
                      "id": {
                        "type": "string"
                      },
                      "timestamp": {
                        "$ref": "#/components/schemas/Instant"
                      },
                      "issuer": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "type",
                      "data",
                      "id",
                      "timestamp",
                      "issuer"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "const": "invoice.canceled"
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "invoiceId": {
                            "type": "string"
                          },
                          "uuid": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "income",
                              "credit_note",
                              "transfer",
                              "payroll",
                              "payment_complement"
                            ]
                          },
                          "direction": {
                            "type": "string",
                            "enum": [
                              "issued",
                              "received"
                            ]
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "draft",
                              "valid",
                              "canceled"
                            ]
                          }
                        },
                        "required": [
                          "invoiceId",
                          "uuid",
                          "kind",
                          "direction",
                          "status"
                        ],
                        "additionalProperties": false
                      },
                      "id": {
                        "type": "string"
                      },
                      "timestamp": {
                        "$ref": "#/components/schemas/Instant"
                      },
                      "issuer": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "type",
                      "data",
                      "id",
                      "timestamp",
                      "issuer"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "const": "sat_sync.completed"
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "period": {
                            "type": "string"
                          },
                          "dateFrom": {
                            "type": "string"
                          },
                          "dateTo": {
                            "type": "string"
                          },
                          "startedAt": {
                            "$ref": "#/components/schemas/Instant"
                          }
                        },
                        "required": [
                          "period",
                          "dateFrom",
                          "dateTo",
                          "startedAt"
                        ],
                        "additionalProperties": false
                      },
                      "id": {
                        "type": "string"
                      },
                      "timestamp": {
                        "$ref": "#/components/schemas/Instant"
                      },
                      "issuer": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "type",
                      "data",
                      "id",
                      "timestamp",
                      "issuer"
                    ],
                    "additionalProperties": false
                  }
                ]
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "status",
          "trigger",
          "attempts",
          "nextAttemptAt",
          "lastAttempt",
          "createdAt",
          "event"
        ],
        "additionalProperties": false
      },
      "Instant": {
        "type": "string",
        "format": "date-time",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
      }
    }
  }
}
```

[OpenAPI 3.1](/openapi.json)

[Receive webhooks](/docs/en/webhooks)

[Event reference](/docs/en/webhooks/events)

Complete documentation: https://exac.mx/docs/en.md
Agent documentation index: https://exac.mx/docs/en/llms.txt
