Webhooks

Webhooks let Dropday notify your system when something happens, for example when an order is forwarded to a supplier or shipped. Integrations can register their own webhook on install with POST webhooks, so merchants don't have to set it up by hand.

Webhooks created through the API also appear on the merchant's Webhooks settings page in Dropday, where they can be toggled, have their secret rotated, and have deliveries inspected and retried.

Installing and reinstalling

A project can't have two webhooks with the same url. Creating one with a URL that's already registered returns 422. On reinstall, call GET webhooks, find your webhook by url, and update it with PATCH webhooks/{id}. On uninstall, remove it with DELETE webhooks/{id}.

Use GET webhooks/events to get the valid event names instead of hardcoding them.

Webhook object

Field	Type	Description
id	Number	The unique identifier of the webhook.
name	String	A name for the webhook, shown on the settings page.
description	String|null	An optional description.
url	String	The URL deliveries are sent to.
events	String[]	The events this webhook subscribes to.
active	Boolean	Inactive webhooks don't receive deliveries.
secret	String	The signing secret. Only returned by POST webhooks.
last_delivered_at	String|null	ISO 8601 timestamp of the last successful delivery.
last_failed_at	String|null	ISO 8601 timestamp of the last failed delivery.
created_at	String	ISO 8601 timestamp when the webhook was created.
updated_at	String	ISO 8601 timestamp when the webhook was last updated.

Receiving deliveries

Each delivery is a JSON POST to the webhook's url:

{
    "id": "9b1d3c4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
    "event": "supplier_order.shipped",
    "created_at": "2026-10-20T12:00:00+00:00",
    "data": {}
}

The contents of data depend on the event. See Event payloads.

Header	Description
X-Dropday-Event	The event name.
X-Dropday-Signature	HMAC-SHA256 of the raw request body, using the webhook's secret as key.

Verify the signature against the raw body before trusting a delivery:

$expected = hash_hmac('sha256', file_get_contents('php://input'), $secret);

if (! hash_equals($expected, $_SERVER['HTTP_X_DROPDAY_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

Respond with any 2xx status within 10 seconds. Other responses, timeouts and connection errors are retried after 1, 5, 15 and 60 minutes (5 attempts in total). Use the envelope id to ignore deliveries you've already processed.