Send Webhooks Reliably And Retry Failed Deliveries Automatically With Convoy

A customer says your system never told theirs about a new order. Your team says it did. Nobody can prove it either way, and the order is sitting in limbo while people trade screenshots. This is what it looks like when the automatic notifications between business systems go wrong, and it gets worse as you add customers and partners. What you want is notifications that keep trying until they land, plus a record of what happened to each one. Convoy does this, and it does it through an API, a way for software to talk directly to other software, so your own applications or an AI assistant can send, trace and resend those notifications without someone digging through logs.

What Convoy does

These notifications are called webhooks. A webhook is one system sending a message to another the moment something happens, such as an order being placed or an invoice being paid. Convoy describes itself as an open-source, cloud-native webhooks gateway, a piece of infrastructure that sits in the middle and takes care of ingesting, storing, debugging and delivering those messages. It covers webhooks you send out as well as webhooks you receive, with retries, payload signing so a receiver can tell a message is genuine, fan-out to many destinations, rate limiting, and portals your customers can use themselves. Convoy says it comes in two forms: a self-hosted project under the Elastic License and a fully managed cloud service in US and EU regions. More on the Convoy website.

What you can get done

Everything here sits under one business capability in our catalog, Webhook & Event Subscription Management, with 53 operations behind it, but it breaks into three jobs.

Settle the argument about whether a message arrived

The first job is getting evidence. An event is the thing that happened, a delivery is the attempt to get word of it to one destination, and each try at that delivery is recorded. When a customer says a message never arrived, your support team can look it up and see what the customer’s system answered, in place of a long email thread.

• GET /v1/projects/{projectID}/eventdeliveries lists deliveries, and can filter by things like destination, event type and status.
• GET /v1/projects/{projectID}/eventdeliveries/{eventDeliveryID} retrieves one delivery and where it stands.
• GET /v1/projects/{projectID}/eventdeliveries/{eventDeliveryID}/deliveryattempts lists every attempt made for that delivery.
• GET /v1/projects/{projectID}/eventdeliveries/{eventDeliveryID}/deliveryattempts/{deliveryAttemptID} shows one attempt in detail, which helps explain why it was rejected.

Recover after something breaks

The second job is cleaning up. When a partner’s system goes down for an afternoon, every message sent during that time fails. Being able to resend them as a batch once it comes back means the outage does not turn into hours of manual reconciliation.

• PUT /v1/projects/{projectID}/eventdeliveries/{eventDeliveryID}/resend retries one failed delivery.
• POST /v1/projects/{projectID}/eventdeliveries/batchretry retries many deliveries at once.
• POST /v1/projects/{projectID}/eventdeliveries/forceresend sends deliveries again even though they already succeeded, useful when the receiver lost the data on its side.

Keep track of who gets what

The third job is knowing your destinations. An endpoint is the web address on the receiving side where messages get delivered. As your customer list grows, you need a plain answer to who is registered to receive your notifications.

• GET /v1/projects/{projectID}/endpoints lists the webhook endpoints registered in a project.

Workflows that put it together

A workflow is a recipe of several calls made in order to finish a real job. APIs.io catalogs 12 for Convoy, and they read like the tasks a support or operations team would actually run:

• Create Event and Trace Delivery publishes an event, finds its delivery and reads the attempts.
• Batch Retry Failed Deliveries detects failed deliveries for a destination and retries them in one call.
• Inspect Delivery Attempts retrieves a delivery, lists its attempts and drills into one.
• Fan Out Event to Owner confirms the destinations belonging to one owner, such as a customer, sends an event to all of them and verifies it landed.
• Define Event Type and Subscribe defines a kind of event, creates a destination and subscribes it to only that kind.
• Attach Filter to Subscription creates a subscription and adds a filter, so a destination receives only the messages it cares about.

Ask for it in plain language

Our conversational overlay for Convoy maps everyday questions to the operation that answers them, so an AI assistant knows which call answers which question. These are the kinds of things you can ask:

• “Which webhook deliveries failed in my project over the last day?”
• “How do I see every attempt Convoy made to deliver one webhook?”
• “Can I retry every failed delivery to an endpoint in one go?”
• “Can I resend a webhook that was already delivered successfully?”
• “Which webhook endpoints are registered in my Convoy project?”

You can browse one in the Convoy Event Deliveries phrasing overlay.

Getting started

Convoy is freemium with self-serve signup. Your developers will want the Convoy documentation and the guide to authentication, which explains how your software proves who it is when it connects. Decide early between running it yourself and using the managed cloud, since that choice determines who looks after it at three in the morning. On APIs.io, see the Convoy profile, the Event Deliveries API, the Delivery Attempts API and the Endpoints API. Think of the last time a customer asked whether a notification ever reached them, and ask your team how long that took to answer.