Webhooks provide a way to receive notifications for your transactions in real time. While your transaction is being processed, its status progresses until it is completed. This makes it very important to get the final status for that transaction, and that's where webhooks are very beneficial.

Setting up your Webhook URL

You can specify your webhook URL in the Developer tools tab of the Settings page of your dashboard. Convoy acts as a central hub for managing all webhook notifications for for your transactions

1. To configure a webhook, you must create an endpoint and subscribe to specific events. The endpoint should include endpoint name, URL and secret
2. You can subscribe to events by configuring how and what the endpoint should receive
3. Convoy will send a POST request to the configured URL whenever an event occurs.

Torus Mara broadcasts notifications for the various events. It has the schema below;

x{
  "id": UUID,
  "event": String,
  "resource_type": String,
  "data": Object
}

The payload sent to your webhook URL would have an event property that identifies what the event is about, and the data attribute which would contain the event data.

Error Handling

Convoy returns standard HTTP status codes:

200 OK – Request successful

400 Bad Request – Invalid input

401 Unauthorized – Invalid API key

403 Forbidden – Insufficient permissions

404 Not Found – Resource not found

500 Internal Server Error – Server error