HMAC SHA-256 · Повтор · Идемпотентность · Песочница
Подписанные webhooks для enterprise клиентов
Как ваша система получает уведомления от мастерской, когда что-то меняется в заказе, поставке, счёте, оповещении о качестве или позиции каталога. Webhooks подписываются, доставляются с уникальными идентификаторами и повторяются с экспоненциальным бэкоффом. Настройка через клиентский портал против валидного HTTPS-эндпоинта.
Как подписывается webhook
Каждый webhook подписывается с HMAC SHA-256. Подпись вычисляется по сырому телу запроса — необработанному — сцепленному с временной меткой и уникальным идентификатором события. Подпись доставляется в заголовке X-Corp-MX-Signature в шестнадцатеричном формате. Вы пересчитываете подпись с общим секретом и сравниваете с полученной. Если они не совпадают, webhook отбрасывается.
Заголовки, приходящие с каждым webhook: X-Corp-MX-Signature с подписью HMAC, X-Corp-MX-Timestamp с UNIX-временной меткой в секундах на момент отправки, X-Corp-MX-Event-Id с уникальным идентификатором события — полезен для идемпотентности — и X-Corp-MX-Event-Type с типом события — order.created, order.approved, order.shipped, invoice.issued, среди других.
События заказа
События заказа охватывают весь жизненный цикл. order.created когда заказ зарегистрирован после одобрения предложения. order.in_production когда производство начинается. order.stage_changed когда стадия продвигается — раскрой, пошив, нанесение, упаковка. order.quality_check когда заказ проходит контроль качества. order.shipped когда заказ покидает мастерскую с номером отслеживания перевозчика. order.delivered когда доставка подтверждена с актом получения.
Для клиентов с несколькими предприятиями событие order.stage_changed включает идентификатор предприятия. Для тиражей с несколькими линейками событие order.line_completed срабатывает, когда каждая линейка завершает производство, до консолидированного пакета. Это позволяет клиенту знать, когда линейка готова, не дожидаясь полного заказа.
События отгрузки
События отгрузки охватывают логистический цикл. shipment.created когда номер отслеживания сгенерирован с перевозчиком. shipment.in_transit когда отгрузка в пути с первым обновлением перевозчика. shipment.out_for_delivery когда отгрузка вышла на доставку. shipment.delivered когда доставка подтверждена с именем получателя и, где применимо, сканированной подписью.
Для многоточечных доставок — многоадресных, мероприятий с несколькими площадками — событие shipment.stop_completed срабатывает, когда каждая точка подтверждена. Информация включает адрес, ответственного за получение, доставленные изделия и подпись, где применимо. Прослеживаемость сохраняется на период гарантии программы.
События счёта и качества
События счёта охватывают цикл выставления счетов. invoice.issued когда счёт CFDI 4.0 отштамповывается SAT и доступен для скачивания. invoice.paid когда оплата подтверждается по согласованному методу и срокам. invoice.canceled когда счёт отменяется по заявленной причине и перевыставляется, где применимо.
События качества охватывают несоответствия и корректирующие действия. quality.non_conformity_opened когда открывается 8D для несоответствия, обнаруженного на производстве или сообщённого клиентом. quality.non_conformity_contained когда выполняется немедленное сдерживание. quality.non_conformity_closed когда 8D закрывается с проверенным корректирующим действием. Клиент может подписаться на все события качества или только на те, что затрагивают его заказы.
Повторы и обработка сбоев
Когда webhook завершается сбоем — эндпоинт возвращает код статуса вне диапазона 2xx — система повторяет автоматически. Политика повторов — пять попыток с экспоненциальным бэкоффом: через шестьдесят секунд, пять минут, тридцать минут, два часа и двенадцать часов. Когда последняя попытка завершается сбоем, событие попадает в очередь ручного разбора и уведомляются технические руководители мастерской и клиента.
Система никогда не доставляет событие дважды без вашего уведомления. Каждое событие несёт уникальный идентификатор в заголовке X-Corp-MX-Event-Id. Вы храните идентификатор и, при получении события, проверяете, что не обработали его раньше. Идемпотентность поддерживается по идентификатору — второе событие с тем же идентификатором отбрасывается.
Настройка через клиентский портал
Клиенты настраивают webhooks через портал — доступный через SSO — с валидным HTTPS-эндпоинтом. Для каждого события клиент выбирает, получать его или нет. Для тиражей с избирательной подпиской — только события заказа, не качества — клиент отмечает нужные события. Настройка сохраняется и применяется мгновенно без ожидания окна обслуживания.
Для клиентов с разделёнными средами — песочница и продакшн — управляются двумя независимыми эндпоинтами. Песочница доставляет события с фиктивными данными для тестирования. Продакшн доставляет реальные события из заказов клиента. Клиент может протетировать интеграцию в песочнице, прежде чем перенести эндпоинт в продакшн одним изменением в портале.
Лучшие практики на стороне клиента
Мы рекомендуем четыре практики. Во-первых, валидируйте подпись HMAC SHA-256 перед обработкой тела — если подпись не совпадает, отбросьте. Во-вторых, валидируйте временную метку с допуском пять минут — если событие старше пяти минут, отбросьте для предотвращения атак повтора. В-третьих, поддерживайте идемпотентность по идентификатору события — храните идентификатор в таблице с TTL двадцать четыре часа.
В-четвёртых, отвечайте быстро — эндпоинт должен вернуть код 2xx в течение пяти секунд. Если внутренняя обработка занимает больше времени, клиент возвращает 2xx немедленно и обрабатывает webhook асинхронно фоновой задачей. Когда эндпоинт возвращает 5xx или таймаут, система обрабатывает это как сбой и запускает повтор.
Настройте ваши webhooks с Corp-Merch.MX
Если вашей технической команде нужна интеграция через webhooks с вашим операционным стеком, давайте поговорим. Мы предоставим эндпоинт песочницы, секрет подписи и полную документацию в вашем формате.
Webhooks предоставляются клиентам с действующей программой и подписанным соглашением об использовании. Документация может обновляться без предварительного уведомления; о мажорных версиях сообщается за тридцать дней. Corp-Merch.MX — мексиканская мастерская корпоративного мерча; мы работаем независимо.