The Webhook API allows an API partner to create and manage webhooks.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/convelio:convelio-webhook-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Convelio Public Webhook API
version: '2.0'
contact:
name: Convelio API Team
email: api@convelio.com
url: https://www.convelio.com
termsOfService: https://www.convelio.com/fr/termes/
license:
name: MIT
url: https://www.convelio.com/fr/termes/
description: '**This document describes the current version (2.0) of the Shipping API.**
The Convelio API is organized around REST.'
x-logo:
url: public/assets/icons/convelio-black-spaced.svg
altText: Convelio logo
servers:
- url: https://api.sandbox.convelio.com/v2
description: Sandbox
- url: https://api.convelio.com/v2
description: Production
security:
- secret_token: []
tags:
- name: Webhook
x-displayName: Webhook API
description: The Webhook API allows an API partner to create and manage webhooks.
paths:
/webhook:
parameters:
- $ref: '#/components/parameters/json-content-type'
- $ref: '#/components/parameters/accept'
get:
summary: List registered webhooks
description: List all webhooks.
operationId: listWebhooks
tags:
- Webhook
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/webhook'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internal-server-error'
post:
summary: Create webhook
description: 'Create a webhook.
Deliveries:
To acknowledge receipt of a webhook delivery, return a 204 OK response with an empty body.
To send a negative acknowledgment for the message, return any other status code.
Webhook deliveries are signed with the API secret token. HTTP header name: X-Convelio-signature
Retry policy:
If a webhook delivery fails, Convelio will retry the delivery for up to 7 days. Retry attempts will start after 60 seconds and will increase exponentially.'
operationId: createWebhook
tags:
- Webhook
requestBody:
$ref: '#/components/requestBodies/webhook'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/webhook'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/unprocessable-entity'
'500':
$ref: '#/components/responses/internal-server-error'
/webhook/{webhookId}:
parameters:
- $ref: '#/components/parameters/webhook-id'
- $ref: '#/components/parameters/json-content-type'
- $ref: '#/components/parameters/accept'
get:
summary: Get webhook
description: Get a webhook.
operationId: getWebhook
tags:
- Webhook
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/webhook'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not-found'
'500':
$ref: '#/components/responses/internal-server-error'
put:
summary: Update webhook
description: Update a webhook.
operationId: updateWebhook
tags:
- Webhook
requestBody:
$ref: '#/components/requestBodies/webhook-update'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/webhook'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not-found'
'422':
$ref: '#/components/responses/unprocessable-entity'
'500':
$ref: '#/components/responses/internal-server-error'
delete:
summary: Delete webhook
description: Delete a webhook.
operationId: deleteWebhook
tags:
- Webhook
responses:
'204':
description: No Content
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not-found'
'500':
$ref: '#/components/responses/internal-server-error'
webhooks:
custom-quote-ready:
post:
summary: Custom Quote Ready Event
description: Sent when a price is available for a custom quote.
operationId: customQuoteReadyEvent
tags:
- Webhook
security:
- convelio_signature: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/custom-quote-ready-event'
responses:
'204':
description: Sent from your server when it accepts the callback.
quote-paid:
post:
summary: Quote Paid Event
description: Sent when a quote was paid
operationId: quotePaidEvent
tags:
- Webhook
security:
- convelio_signature: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/quote-paid-event'
responses:
'204':
description: Sent from your server when it accepts the callback.
order-created:
post:
summary: Order Created Event
description: Sent when an order is created through the API.
operationId: orderCreatedEvent
tags:
- Webhook
security:
- convelio_signature: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/orde-created-event'
responses:
'204':
description: Sent from your server when it accepts the callback.
shipment-status-changed:
post:
summary: Shipment Status Changed Event
description: Sent when a new shipment status is published.
operationId: shipmentStatusChangedEvent
tags:
- Webhook
security:
- convelio_signature: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/shipment-status-changed-event'
responses:
'204':
description: Sent from your server when it accepts the callback.
document-ready:
post:
summary: Document Ready Event
description: Sent when a new document is available.
operationId: documentReadyEvent
tags:
- Webhook
security:
- convelio_signature: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/document-ready-event'
responses:
'204':
description: Sent from your server when it accepts the callback.
components:
schemas:
triggering-event-name:
title: TriggeringEventName
type: string
enum:
- custom_quote_ready
- quote_paid
- order_created
- shipment_status_changed
- document_ready
http-error:
title: HttpError
x-tags:
- Error responses
description: 'The error model for the API follow the Content-Type **application/problem+json** defined by the [IETF RFC 7807](https://tools.ietf.org/html/rfc7807).
Description of the errors:
- Bad Request (400): The URL requested is not valid.
- Unauthorized (401): Token not found.
- Forbidden (403): You are authenticated but not allowed to execute the action.
- Not Found (404): Page not found.
- Unprocessable Entity (422): The server was unable to process the request.
- Internal Server Error (500): There is an internal problem on our server.
- Service Unavailable (503): The server is not ready to handle the request.
'
type: object
properties:
type:
type: string
example: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
description: 'A URL to a page with more details regarding the problem.
The primary identifier for the problem.
It''s typically an absolute URL that leads to an HTML page containing human-readable documentation regarding the problem.'
title:
type: string
description: Short human-readable summary of the problem.
example: Forbidden
status:
type: integer
description: 'The HTTP status code.
It''s always the same as the status code in the HTTP header.
It''s only included for the convenience of the consumer.'
example: 403
minimum: 100
detail:
type: string
description: Human-readable description of this specific problem.
example: Forbidden
required:
- type
- title
- status
- detail
shipment-status-changed-event:
title: ShipmentStatusChangedEvent
type: object
properties:
event:
type: string
enum:
- shipment_status_changed
created:
type: string
format: date-time
payload:
type: object
properties:
order_id:
type: string
description: The Order ID.
format: uuid
status:
$ref: '#/components/schemas/shipment-status'
quote-paid-event:
title: QuotePaidEvent
type: object
properties:
event:
type: string
enum:
- quote_paid
created:
type: string
format: date-time
payload:
type: object
properties:
quote_id:
type: string
description: The Quote ID.
format: uuid
tracking_link:
type: string
description: Link to follow the progress of the shipping order.
format: uri
example: https://tracking.convelio.com/example
orde-created-event:
title: OrderCreatedEvent
type: object
properties:
event:
type: string
enum:
- order_created
created:
type: string
format: date-time
payload:
type: object
properties:
quote_id:
type: string
description: The Quote ID.
format: uuid
order_id:
type: string
description: The Order ID.
format: uuid
shipment-status:
title: ShipmentStatus
description: 'The shipment status of the tracked order. Possible values:
- shipment_created: The Order has been booked and our team is planning collection at the pickup location.
- picked_up: The items have been collected at the pickup location.
- packing_in_progress: The items are being packed at one of our crating center for more safety.
- export_in_progress: The shipment has left our crating center to be sent abroad.
- freight_in_transit: The shipment is on its way to the delivery location.
- import_in_progress: The shipment has arrived at country of destination.
- out_for_delivery: The shipment has arrived the destination facility and the carrier is about to deliver the shipment.
- shipment_completed: Home, sweet home! The shipment has been delivered to the delivery location.
- on_hold: The shipment has temporarily been paused.
- canceled: The shipment has been canceled for some reason.'
type: string
enum:
- shipment_created
- picked_up
- packing_in_progress
- export_in_progress
- freight_in_transit
- import_in_progress
- out_for_delivery
- shipment_completed
- on_hold
- canceled
custom-quote-ready-event:
title: CustomQuoteReadyEvent
type: object
properties:
event:
type: string
enum:
- custom_quote_ready
created:
type: string
format: date-time
payload:
type: object
properties:
quote_id:
type: string
description: The Quote ID.
format: uuid
document-ready-event:
title: DocumentReadyEvent
type: object
properties:
event:
type: string
enum:
- document_ready
created:
type: string
format: date-time
payload:
type: object
properties:
order_id:
type: string
description: The Order ID.
format: uuid
document_type:
type: string
description: The type of document.
dashboard_order_link:
type: string
description: Link to see the details of the shipping order.
format: uri
webhook:
title: Webhook
x-tags:
- Models
type: object
description: A webhook (also called a web callback or HTTP push API) is a way for an app to provide other applications with real-time information.
properties:
id:
type: string
description: Identifier of the webhook
format: uuid
example: df35ed86-2151-437d-839e-ef650313a067
readOnly: true
url:
$ref: '#/components/schemas/webhook-url'
triggering_event_name:
$ref: '#/components/schemas/triggering-event-name'
creation_date:
type: string
format: date-time
example: '2020-01-01T00:00:00Z'
readOnly: true
required:
- url
- triggering_event_name
webhook-update:
title: RequestBodyUpdateWebhook
type: object
properties:
url:
$ref: '#/components/schemas/webhook-url'
required:
- url
http-unprocessable-entity-error:
title: HttpUnprocessableEntityError
x-tags:
- Error responses
type: object
allOf:
- $ref: '#/components/schemas/http-error'
- properties:
status:
example: 422
validation_messages:
type: object
description: Validation messages are only returned when your request have a body and the body is invalid.
properties:
'{field_name}':
type: object
description: 'The name of the field which is wrong in your request. Example: "delivery_type"'
properties:
'{error_title}':
type: string
description: 'The title of the error. Example: "deliveryTypeInvalid"'
example: 'Invalid delivery type. Valid values are: curbside, white_glove'
required:
- '{field_name}'
webhook-url:
title: WebhookUrl
description: URL to receive webhooks.
type: string
format: uri
pattern: ^https?:\/\/(?:www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b(?:[-a-zA-Z0-9()@:%_\+.~#?&\/=]*)$
maxLength: 255
example: https://example.com/webhook
responses:
unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/http-error'
example:
type: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
title: Unauthorized
status: 401
detail: Token not found.
forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/http-error'
example:
type: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
title: Forbidden
status: 403
detail: You are authenticated but not allowed to execute the action.
internal-server-error:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/http-error'
example:
type: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
title: Internal Server Error
status: 500
detail: There is an internal problem on our server.
unprocessable-entity:
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/http-unprocessable-entity-error'
example:
type: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
title: Unprocessable Entity
status: 422
detail: The server was unable to process the request.
validation_messages:
'{field_name}':
'{error_title}': 'Invalid delivery type. Valid values are: curbside, white_glove'
not-found:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/http-error'
example:
type: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
title: Not Found
status: 404
detail: Page not found.
parameters:
webhook-id:
name: webhookId
description: Webhook ID
in: path
schema:
type: string
required: true
json-content-type:
name: Content-Type
description: Content-Type header should be sent and should be `application/vnd.convelio-shipping.v2+json`
in: header
schema:
type: string
enum:
- application/json
- application/vnd.convelio-shipping.v2+json
default: application/json
accept:
description: Accept header should be sent and should be `application/json`
name: Accept
in: header
schema:
type: string
enum:
- '*/*'
- application/json
default: application/json
requestBodies:
webhook:
content:
application/json:
schema:
$ref: '#/components/schemas/webhook'
application/vnd.convelio-shipping.v2+json:
schema:
$ref: '#/components/schemas/webhook'
webhook-update:
content:
application/json:
schema:
$ref: '#/components/schemas/webhook-update'
application/vnd.convelio-shipping.v2+json:
schema:
$ref: '#/components/schemas/webhook-update'
securitySchemes:
convelio_signature:
name: X-Convelio-signature
description: An HMAC SHA256 signature created with the body data and the API secret token.
in: header
type: apiKey
secret_token:
name: Authorization
type: apiKey
in: header
description: token <your_token_here>
x-convelio-example: token {{secret_token}}
x-convelio-sensitive: true
x-tagGroups:
- name: Endpoints
tags:
- shipping
- webhook
- name: Schemas
tags:
- Error responses
- Models
- Enums
- name: Resources
tags:
- api-status-page