What is a webhook?

A webhook is an automatic message a service sends to a URL you’ve set up in advance whenever a particular event happens. Instead of your tools going to check for news, the service tells them.

Say someone signs up through your class’s registration form. You might want a message in your team chat right away, or the new student added to your list. Understanding webhooks helps you judge whether that kind of “react as soon as it happens” connection is possible, and what the receiving side has to take care of, such as confirming a message is genuine and handling one that arrives twice.

What are webhooks for?

With an API, your program asks a service for something when it needs it. A webhook works the other way around: the service where something happened sends a message to your URL.

Webhooks are often used to:

• Post to your team chat when someone answers your class’s registration form
• Start enrolling a student when a payment for an online course goes through
• Add a small company’s new inquiries to a customer management tool automatically

“Webhook” isn’t the name of a single formal standard. It’s a common name for a widely used pattern, so the exact message format and the way you verify messages vary from service to service. When you connect one, check the sending service’s documentation.

How are webhooks different from polling?

The other way to find out about events is polling: asking an API “Anything new?” at regular intervals.

Think of mail. Polling is like walking to the mailbox every hour. A webhook is like a doorbell that rings when a parcel arrives.

	Polling	Webhook
Who acts	The receiver keeps asking	The service where it happened sends
How soon you know	At the next check	Right after the event
Wasted requests	Asks even when nothing changed	Only sends when there’s an event
What the receiver needs	A program that asks	An https URL reachable from the internet

Polling has its strengths. The receiver doesn’t need a public URL and can fetch updates whenever it suits. In practice, many integrations combine the two: they receive urgent events by webhook and occasionally poll the API to catch anything that slipped through.

How does a webhook work?

A webhook usually works like this:

1. The receiver registers a URL, called the endpoint, with the sending service.
2. Something happens in the sending service.
3. The service sends details of the event to the endpoint in an HTTP POST request.
4. The endpoint checks the message and replies with a 2xx status code to confirm it arrived.
5. If there’s no reply or the reply is an error, the service tries again later.

What is an event?

An event is the thing that triggers a webhook, such as “a form answer arrived”, “a payment succeeded” or “a booking was cancelled”. Events often have names like form.submission.created. Some services let you choose which events to receive.

What is a payload?

The payload is the content of the message. It’s usually JSON and includes the event name, when it happened and the related data. Some services include all the data you need. Others send only an ID and expect you to fetch the details through their API.

An endpoint should reply with a 2xx code as quickly as possible. Record that the message arrived, then do slow work, such as sending an email or updating another tool, afterwards. Otherwise the sender may give up waiting, treat the delivery as failed and send it again.

What does a signature prove?

Anyone on the internet can send a request to your endpoint’s URL, so someone who learns it could send fake messages. Signatures let you tell real messages from fakes.

Many services sign messages with HMAC, a method that uses a secret key and a hash function to turn a message into a fixed-length value. MDN’s glossary entry on HMAC has more detail. Only the sender and the receiver know the secret. The sender calculates a value from the body and the secret and puts it in a header. The receiver does the same calculation with its copy of the secret. If the values match, the message came from someone who knows the secret and wasn’t changed on the way.

When you verify a signature:

1. Calculate it from the raw body exactly as it arrived. If you parse the JSON and write it out again, spacing or order can change and the values won’t match.
2. Use exactly the inputs and method the service documents. Some services sign the timestamp and body joined together, for example.
3. Compare the values with a method whose timing doesn’t depend on the contents. Many programming languages provide one.
4. If the signature includes a timestamp, reject messages that are too old. This blocks replay attacks, where someone copies a real message and sends it again later.
5. Don’t process messages that don’t match. Reject them.

Treat the signing secret like an API key. Keep it out of browser code and public places, and replace it if it may have leaked.

What happens when a delivery fails or arrives twice?

If your endpoint is down or too slow, most services try again several times, waiting longer between attempts, for example after 1 minute, then 5, then 30.

Retries also mean the same message can arrive more than once. For example, your endpoint may finish its work, but the connection drops before the reply reaches the sender, so the sender treats it as a failure and tries again. Messages also don’t always arrive in the order the events happened.

So build the receiving side so that handling the same message twice has the same result as handling it once. This property is called being idempotent.

• Record the ID that comes with each message (a delivery or event ID). If an ID you’ve already handled arrives, do nothing and reply with 2xx.
• Before adding someone to a list, check whether the same sign-up is already there.
• Don’t rely on arrival order. If it matters, compare event timestamps and keep the newest.

Retries have limits too. If your endpoint was down for a long time, check the sending service’s delivery log or its API for anything you missed.

Summary

• A webhook is a way for a service to tell you when something happens.
• Compared with polling, you find out sooner and send fewer wasted requests.
• Check each message’s signature and timestamp to confirm it’s genuine.
• The same message can arrive more than once, so use its ID to make handling it idempotent.