Webhooks

Connect a webhook URL to get order events sent to your own system. Medialister sends them to that URL when an order needs your action, so you do not have to poll.

Webhooks work for both sides. Clients who order through the API hear what the publisher did. Publishers hear what the client did. The event is short: it tells you what happened and to which order. Your system then reads the order through the API.

The Integrations page appears only for organization admins, and only after Medialister has turned webhooks on for your organization. If you do not see it, contact support.

What Do You Need Before You Start

Where to Find the Webhook Settings

Open the account menu and choose Settings. In the sidebar, under Organization Settings, choose Integrations. The page has a Webhooks section with an Endpoint panel.

The page manages the URL of the side that you have open. In the client dashboard you connect the client URL. In the publisher dashboard you connect the publisher URL.

What Does the URL Need

• The URL must start with https:// and accept POST requests with a JSON body.

• Medialister sends a test request (a ping) to the URL when you connect. Your server must answer it with a 2xx status and the plain-text body pong. If not, the connection fails and the field shows what your server answered.

• Your server must answer each other event with a 2xx status in 10 seconds or less. Put the work in a queue and answer quickly.

• Your server must check the signature of each event, but not of the ping. See "How to Check That an Event Is from Medialister".

• Each organization has one URL per side. Publisher accounts receive events for orders on their media, and client accounts receive events for orders they placed.

How to Connect a URL

1. Enter your address in the `Webhook URL` field, for example `https://yourdomain.com/webhooks`.

2. Click `Connect`.

Once the connection succeeds, the field shows "URL verified" with the date and time, and the button changes to Disconnect.

If the test request fails, the URL is not saved. Correct your server, then click Connect again.

Which Events Do You Get

You hear what the other side did, never your own actions. Clients hear what the publisher or Medialister did. Publishers hear what the client did, and only when the order is with them.

The full list of events, with their reasons and fields, is in the API reference of your side:

How to Check That an Event Is from Medialister

Each endpoint has a signing secret that starts with whsec_. The secret is shown one time only, when the URL is first registered. Keep it on your server. If you do not have it, get a new one with the rotate-secret route in the API reference. The old secret stops working at once.

Each request carries three headers:

• Medialister-Signature: a timestamp and an HMAC SHA-256 signature of the body, so you can check that the request came from Medialister.

• Medialister-Event-Id: the ID of the event. It is the same on each retry.

• Medialister-Event-Type: the event type.

Reject a request with a wrong signature or with a timestamp that is more than 5 minutes old. The ping at setup is the one exception: it is signed with the new secret before you have it, so do not require a signature for it. The code sample is in the reference.

How Do Delivery and Retries Work

Answer with a 2xx status to confirm delivery. Each other answer, a timeout and a redirect cause a retry.

That is 9 attempts in about 18 hours. If the last one fails, the event is marked as failed.

A retry sends the same body with the same event ID. Use Medialister-Event-Id to ignore an event that you already processed.

How to Manage Webhooks Through the API

Your developers can do the same work with the API key: register the URL, send a test ping, pause the delivery, get a new signing secret and read what Medialister sent and what your server answered. The routes are in the reference of your side.

What Are the Rate Limits

The events that Medialister sends to your server have no limit on your side. The limits apply to the requests that your system sends to the API, for example when it reads an order after an event. They are counted for each API key.

When you go above a limit, the API answers 429. Wait, then send the request again. Do not retry in a tight loop.

How to Disconnect or Change the URL

Click Disconnect to turn event delivery off. The field becomes editable again, so you can enter a different URL and click Connect.

An endpoint cannot be deleted. To stop the events, disconnect it.

What to Do If Something Does Not Work

Need Help?

Write to [email protected]. Give the event ID and the time of the request.