> ## Documentation Index
> Fetch the complete documentation index at: https://docs.afriex.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Trigger Test Webhook
> Fires a real signed webhook to the business's configured callback URL using a real entity (customer, payment method, transaction, or checkout session) as the payload. Useful for testing webhook handlers in sandbox without manufacturing the underlying activity. **This endpoint is only available in the sandbox/staging environment and will return a `403 Forbidden` response in production.**
Fire a real signed webhook from sandbox using an existing entity as the payload. Use this to test your webhook handler without having to manufacture the underlying activity.
This endpoint is only available in the **sandbox/staging** environment and returns a `403 Forbidden` response in production.
To test transaction webhooks end to end, you can also let a sandbox transaction settle on its own: it reaches a final status within \~1-2 minutes and sends `TRANSACTION.UPDATED`. Set `meta.reference` to a value containing `fail` to test a `FAILED` outcome, or any other value for `SUCCESS`. See [Testing transaction outcomes in sandbox](/development#testing-transaction-outcomes-in-sandbox).
## How it works
1. Create or look up an existing entity in sandbox.
2. Call this endpoint with the matching `event` name and the entity's ID.
3. Afriex delivers a real, signed webhook to your configured callback URL using that entity as the payload.
Because the payload is a real entity, your handler verifies the signature and processes the event exactly the same way it would in production.
## What to pass as `entityId`
| Event family | `entityId` |
| -------------------- | ----------------------- |
| `CUSTOMER.*` | The customer ID |
| `PAYMENT_METHOD.*` | The payment method ID |
| `TRANSACTION.*` | The transaction ID |
| `CHECKOUT_SESSION.*` | The checkout session ID |
## OpenAPI
````yaml POST /api/v1/webhooks/trigger
openapi: 3.1.0
info:
title: Afriex Business API
version: 1.0.8
description: >-
Welcome to the Afriex Business API. This API allows you to manage customers,
process payments, handle payouts, and receive real-time notifications via
webhooks.
For detailed guidance on authentication, pagination, error handling, and
webhooks, please refer to the [dedicated guides](https://docs.afriex.com) in
the top bar. The guide provides a step-by-step instructions to help you
integrate seamlessly.
termsOfService: https://www.afriex.com/terms-and-condition
contact:
name: Afriex API Support
email: eng@afriex.co
url: https://docs.afriex.com
license:
name: Proprietary
url: https://www.afriex.com/terms-and-condition
servers:
- url: https://sandbox.api.afriex.com
description: Staging Base URL
- url: https://api.afriex.com
description: Production Base URL
security:
- ApiKey: []
tags:
- name: Customers
description: Create and manage your customers.
- name: Payment Methods
description: Register and resolve customer payout and collection methods.
- name: Transactions
description: Create and track deposits, withdrawals, and swaps.
- name: Balance
description: View and top up your business wallet balances.
- name: Rates
description: Fetch real-time exchange rates.
- name: Checkout Sessions
description: Create hosted checkout sessions.
- name: Webhooks
description: Webhook event payloads and sandbox webhook testing.
paths:
/api/v1/webhooks/trigger:
parameters:
- $ref: '#/components/parameters/x-api-version'
post:
tags:
- Webhooks
summary: Trigger a test webhook (sandbox-only)
description: >-
Fires a real signed webhook to the business's configured callback URL
using a real entity (customer, payment method, transaction, or checkout
session) as the payload. Useful for testing webhook handlers in sandbox
without manufacturing the underlying activity. **This endpoint is only
available in the sandbox/staging environment and will return a `403
Forbidden` response in production.**
operationId: triggerWebhook
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- event
- entityId
properties:
event:
$ref: '#/components/schemas/WebhookEventName'
entityId:
type: string
description: >-
The identifier of the entity to send in the webhook payload.
Must be a UUID v4 when `event` is
`CHECKOUT_SESSION.CREATED`; otherwise must be the
24-character hexadecimal id of the relevant customer,
payment method, or transaction (the id returned when it was
created).
examples:
- 69528240ba52c13b669fb239
examples:
transactionEvent:
summary: Trigger a transaction webhook
value:
event: TRANSACTION.UPDATED
entityId: 6952826eba52c13b669fb263
checkoutSessionEvent:
summary: Trigger a checkout session webhook (UUID entityId)
value:
event: CHECKOUT_SESSION.CREATED
entityId: f47ac10b-58cc-4372-a567-0e02b2c3d479
responses:
'200':
description: Webhook triggered successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: Details of the queued webhook delivery.
properties:
queued:
type: boolean
description: Always true; the webhook delivery was queued.
event:
$ref: '#/components/schemas/WebhookEventName'
entityId:
type: string
description: The id of the entity used as the webhook payload.
deliveryUrl:
type: string
description: >-
The business webhook callback URL the event was queued
to.
examples:
queued:
summary: Webhook queued
value:
data:
queued: true
event: TRANSACTION.UPDATED
entityId: 6952826eba52c13b669fb263
deliveryUrl: https://merchant.example.com/webhooks
'400':
description: Invalid request body.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized - Invalid business API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: >-
Forbidden - This endpoint is not available in the production
environment.
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
- Not allowed
'500':
description: Server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-codeSamples:
- lang: TypeScript
label: Afriex SDK
source: |
const result = await afriex.webhooks.triggerTestWebhook({
event: "TRANSACTION.UPDATED",
resourceId: "transaction-id",
});
console.log(result); // { success: true, message: "..." }
components:
parameters:
x-api-version:
name: x-api-version
in: header
required: false
description: >-
API version in ISO 8601 format (e.g. 2025-12-28). Defaults to latest
stable.
schema:
type: string
schemas:
WebhookEventName:
type: string
description: The webhook event identifier.
enum:
- CUSTOMER.CREATED
- CUSTOMER.UPDATED
- CUSTOMER.DELETED
- PAYMENT_METHOD.CREATED
- PAYMENT_METHOD.UPDATED
- PAYMENT_METHOD.DELETED
- TRANSACTION.CREATED
- TRANSACTION.UPDATED
- CHECKOUT_SESSION.CREATED
ErrorResponse:
type: object
properties:
code:
type: string
description: Machine-readable error code.
error:
type: string
description: Human-readable error message.
details:
$ref: '#/components/schemas/ErrorDetails'
ErrorDetails:
type: object
properties:
errorMessage:
type: string
description: Detailed/technical error message.
friendlyMessage:
type: string
description: User-facing error message safe to display.
data:
type: object
description: >-
Optional caller-safe context for the error. On a customer-create
uniqueness conflict (EMAIL_ALREADY_EXISTS /
PHONE_NUMBER_ALREADY_EXISTS) this carries the existing customer's
id, so you can adopt it without a follow-up lookup.
properties:
customerId:
type: string
description: Id of the existing customer (on a create conflict).
securitySchemes:
ApiKey:
type: apiKey
in: header
name: x-api-key
description: >-
Static business API key issued from the dashboard. A business can
provision **multiple API keys**, each scoped to a configurable set of
**permissions** (e.g. read transactions, create deposits, etc).
Permissions are chosen per key at creation time in the dashboard and may
be revoked by deleting the key. Requests made with a key that does not
include the permission required by the target endpoint will be rejected
with a `403 Forbidden` response; an unrecognised, malformed or revoked
key returns `401 Unauthorized`. Manage your keys and their permissions
under **Developer → API keys** in the dashboard.
````