CourierHub Docs

Εμφάνιση

Διαχείριση webhook endpoints ​

Τα webhook endpoints είναι τα URLs του συστήματός σας στα οποία το CourierHub στέλνει ειδοποιήσεις (shipment.created, shipment.updated, shipment.deleted). Εδώ περιγράφονται οι κλήσεις για τη δημιουργία και τη διαχείρισή τους. Για το περιεχόμενο των ειδοποιήσεων, την επαλήθευση υπογραφής και τα retries δείτε τη σελίδα Webhooks.

Μπορείτε να τα διαχειριστείτε και από το περιβάλλον πελάτη: Ρυθμίσεις > Webhooks (απαιτεί το δικαίωμα webhooks του λογαριασμού).

WARNING

Θα πρέπει να συμπεριλάβετε το API Token σας σε κάθε αίτημα ως Bearer Token. Αντικαταστήστε το YOUR_TOKEN με το API Token του καταστήματος (chub_...). Δείτε το Overview.

MethodURIΠεριγραφή
GET/api/v2/webhook-endpointsΛίστα endpoints (σελιδοποιημένη)
POST/api/v2/webhook-endpointsΔημιουργία endpoint (επιστρέφει το secret)
GET/api/v2/webhook-endpoints/{id}Στοιχεία endpoint
PATCH/api/v2/webhook-endpoints/{id}Ενημέρωση endpoint
DELETE/api/v2/webhook-endpoints/{id}Διαγραφή endpoint
POST/api/v2/webhook-endpoints/{id}/rotate-secretΝέο secret
GET/api/v2/webhook-endpoints/{id}/deliveriesΙστορικό αποστολών (σελιδοποιημένο)
POST/api/v2/webhook-endpoints/{id}/testΑποστολή δοκιμαστικού ping

Headers για όλα: Authorization: Bearer YOUR_TOKEN. Στα POST και PATCH με body στέλνετε και Content-Type: application/json.

Κανόνες ​

  • Έως 5 endpoints ανά πελάτη. Η δημιουργία έκτου επιστρέφει 422.
  • Το url πρέπει να είναι https στη θύρα 443 (μην βάζετε άλλη θύρα) και να δείχνει σε δημόσια διεύθυνση. Δεν επιτρέπονται: http, URLs με user:password@, διευθύνσεις IP ιδιωτικών δικτύων / loopback (π.χ. localhost, 10.x.x.x, 192.168.x.x), hostnames χωρίς τελεία ή με αριθμητικό τέλος, και hosts που δεν επιλύονται σε διεύθυνση (DNS). Ο έλεγχος γίνεται στη δημιουργία και ξανά πριν από κάθε αποστολή.
  • Το secret (whsec_...) εμφανίζεται μόνο μία φορά: στην απάντηση της δημιουργίας και της rotate-secret. Δεν μπορεί να ξαναδιαβαστεί. Αποθηκεύστε το αμέσως στο σύστημα που λαμβάνει τα webhooks.
  • Το events είναι πίνακας με τιμές από shipment.created, shipment.updated, shipment.deleted. Με events: null (ή χωρίς events στη δημιουργία) το endpoint λαμβάνει όλα τα γεγονότα. Ο πίνακας δεν μπορεί να είναι κενός ([]): για όλα τα γεγονότα στείλτε null. Το ping δεν συμπεριλαμβάνεται στη λίστα: στέλνεται μόνο κατά τη δοκιμή.
  • Τα endpoints που ανήκουν σε άλλον λογαριασμό επιστρέφουν 404 (όχι 403).

Το αντικείμενο endpoint ​

Variable NameTypeDescription
idIntegerΤο ID του endpoint.
urlStringΤο URL παραλαβής.
eventsArray ή nullΤα γεγονότα που λαμβάνει. null = όλα.
is_activeBooleanΑν είναι ενεργό. Τα ανενεργά endpoints δεν λαμβάνουν γεγονότα (αλλά δέχονται δοκιμή ping).
descriptionString ή nullΕλεύθερη περιγραφή (έως 255 χαρακτήρες).
secretStringΤο secret υπογραφής. Μόνο στις απαντήσεις δημιουργίας και rotate-secret.
created_at, updated_atStringISO 8601, UTC με Z, δείτε το Overview.

GET /webhook-endpoints ​

Επιστρέφει τα endpoints σας, ταξινομημένα κατά id, με cursor pagination (per_page, cursor). Το secret δεν περιλαμβάνεται.

Παράδειγμα επιτυχημένης αναζήτησης.

json
{
    "data": [
        {
            "id": 1,
            "url": "https://erp.example.gr/hooks/courierhub",
            "events": null,
            "is_active": true,
            "description": "ERP",
            "created_at": "2026-10-14T07:00:00Z",
            "updated_at": "2026-10-14T07:00:00Z"
        }
    ],
    "links": {
        "next": null,
        "prev": null
    },
    "meta": {
        "per_page": 50,
        "next_cursor": null,
        "prev_cursor": null
    }
}
bash
curl https://courierhub.gr/api/v2/webhook-endpoints \
  -H "Authorization: Bearer chub_YOUR_API_TOKEN"

POST /webhook-endpoints ​

Δημιουργεί ένα endpoint και επιστρέφει 201 Created με το secret.

Μεταβλητές αποστολής ​

Variable NameTypeUsageRequired
urlStringΤο URL παραλαβής. https, θύρα 443, δημόσιος host, έως 2048 χαρακτήρες.*
eventsArray ή nullΤα γεγονότα: shipment.created, shipment.updated, shipment.deleted. Αν λείπει ή είναι null: όλα. Μη κενός πίνακας, χωρίς διπλότυπα.
is_activeBooleanΑν είναι ενεργό. Προεπιλογή true.
descriptionString ή nullΠεριγραφή, έως 255 χαρακτήρες.

Παράδειγμα επιτυχημένης δημιουργίας (HTTP 201).

Το secret εμφανίζεται μόνο εδώ. Αποθηκεύστε το τώρα.

json
{
    "data": {
        "id": 1,
        "url": "https://erp.example.gr/hooks/courierhub",
        "events": null,
        "is_active": true,
        "description": "ERP",
        "secret": "whsec_8nQ2vK5tR1yLwZ7pD4mC9sJ6hB3fG0aE2uXcT1oVbNk",
        "created_at": "2026-10-14T07:00:00Z",
        "updated_at": "2026-10-14T07:00:00Z"
    }
}

Παράδειγμα σφάλματος (http και μη έγκυρο γεγονός).

json
{
    "message": "The given data was invalid.",
    "code": "validation_failed",
    "errors": {
        "url": [
            "The url must use https."
        ],
        "events.0": [
            "The selected events.0 is invalid."
        ]
    }
}

Παράδειγμα σφάλματος (έκτο endpoint).

json
{
    "message": "The given data was invalid.",
    "code": "validation_failed",
    "errors": {
        "url": [
            "You can register at most 5 webhook endpoints."
        ]
    }
}
bash
curl -X POST https://courierhub.gr/api/v2/webhook-endpoints \
  -H "Authorization: Bearer chub_YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://erp.example.gr/hooks/courierhub",
    "events": ["shipment.created", "shipment.updated"],
    "description": "ERP"
  }'

GET /webhook-endpoints/{id} ​

Επιστρέφει ένα endpoint (χωρίς secret). Αν δεν υπάρχει ή ανήκει σε άλλον λογαριασμό:

Παράδειγμα σφάλματος.

json
{
    "message": "Resource not found.",
    "code": "not_found"
}
bash
curl https://courierhub.gr/api/v2/webhook-endpoints/1 \
  -H "Authorization: Bearer chub_YOUR_API_TOKEN"

PATCH /webhook-endpoints/{id} ​

Ενημερώνει μόνο τα πεδία που στέλνετε. Δέχεται τα ίδια πεδία με τη δημιουργία (url, events, is_active, description), όλα προαιρετικά. Με "events": null το endpoint γίνεται συνδρομητής σε όλα τα γεγονότα. Με "is_active": false το απενεργοποιείτε χωρίς να το διαγράψετε. Το secret δεν αλλάζει (και δεν επιστρέφεται).

Παράδειγμα επιτυχημένης ενημέρωσης.

json
{
    "data": {
        "id": 1,
        "url": "https://erp.example.gr/hooks/courierhub",
        "events": [
            "shipment.created",
            "shipment.updated"
        ],
        "is_active": true,
        "description": "ERP παραγωγής",
        "created_at": "2026-10-14T07:00:00Z",
        "updated_at": "2026-10-15T07:00:00Z"
    }
}
bash
curl -X PATCH https://courierhub.gr/api/v2/webhook-endpoints/1 \
  -H "Authorization: Bearer chub_YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"events": ["shipment.created", "shipment.updated"], "description": "ERP παραγωγής"}'

DELETE /webhook-endpoints/{id} ​

Διαγράφει το endpoint και το ιστορικό αποστολών του. Επιστρέφει 204 No Content χωρίς body. Οι αποστολές που εκκρεμούσαν δεν θα σταλούν.

bash
curl -X DELETE https://courierhub.gr/api/v2/webhook-endpoints/1 \
  -H "Authorization: Bearer chub_YOUR_API_TOKEN"

POST /webhook-endpoints/{id}/rotate-secret ​

Δημιουργεί νέο secret και το επιστρέφει (μία φορά).

Το παλιό secret παύει να ισχύει αμέσως

Δεν υπάρχει περίοδος χάριτος ούτε επικάλυψη. Από τη στιγμή της κλήσης όλες οι αποστολές, και οι επαναλήψεις (retries) αποστολών που είχαν δημιουργηθεί πριν, υπογράφονται με το νέο secret. Ενημερώστε το σύστημα που λαμβάνει τα webhooks αμέσως, αλλιώς οι επόμενες αποστολές θα απορρίπτονται από την επαλήθευση υπογραφής.

Παράδειγμα επιτυχημένης κλήσης.

json
{
    "data": {
        "id": 1,
        "url": "https://erp.example.gr/hooks/courierhub",
        "events": [
            "shipment.created",
            "shipment.updated"
        ],
        "is_active": true,
        "description": "ERP παραγωγής",
        "secret": "whsec_Tz4Lp9Wq2KdXe7Ry1NcBv5MhGs8UaJf3OiQ6YtE0ZmA",
        "created_at": "2026-10-14T07:00:00Z",
        "updated_at": "2026-10-16T05:00:00Z"
    }
}
bash
curl -X POST https://courierhub.gr/api/v2/webhook-endpoints/1/rotate-secret \
  -H "Authorization: Bearer chub_YOUR_API_TOKEN"

POST /webhook-endpoints/{id}/test ​

Στέλνει αμέσως ένα γεγονός ping στο endpoint, υπογεγραμμένο όπως οι πραγματικές αποστολές, και επιστρέφει την απάντηση που έδωσε το σύστημά σας. Κάνει μία προσπάθεια (χωρίς retries), λειτουργεί και σε ανενεργά endpoints (δοκιμάστε ένα URL πριν το ενεργοποιήσετε) και καταγράφεται στο ιστορικό αποστολών με event_type ping. Δεν έχει body.

Το ίδιο κάνει το κουμπί Αποστολή δοκιμής στο περιβάλλον πελάτη. Δείτε Δοκιμή και ενεργοποίηση.

Variable NameTypeDescription
delivery_idIntegerΤο ID της αποστολής στο ιστορικό.
event_idStringΤο UUID του γεγονότος (το ίδιο με την κεφαλίδα CourierHub-Delivery).
successBooleantrue αν το σύστημά σας απάντησε με 2xx.
response_statusInteger ή nullΤο HTTP status της απάντησης. null αν δεν υπήρξε απάντηση (σφάλμα σύνδεσης, timeout ή μη επιτρεπτό URL).
response_time_msIntegerΟ χρόνος απάντησης σε milliseconds.
response_bodyString ή nullΤο body της απάντησης (έως 2048 bytes) ή το σφάλμα σύνδεσης.

Παράδειγμα επιτυχημένης δοκιμής.

json
{
    "data": {
        "delivery_id": 1,
        "event_id": "8661d116-e936-4624-b877-3ad18c9e15cf",
        "success": true,
        "response_status": 200,
        "response_time_ms": 28,
        "response_body": "OK"
    }
}

Η κλήση επιστρέφει 200 ακόμα κι αν η δοκιμή αποτύχει: ελέγξτε το success.

bash
curl -X POST https://courierhub.gr/api/v2/webhook-endpoints/1/test \
  -H "Authorization: Bearer chub_YOUR_API_TOKEN"

GET /webhook-endpoints/{id}/deliveries ​

Το ιστορικό των αποστολών του endpoint, νεότερες πρώτα, με cursor pagination. Οι αποστολές διατηρούνται για 30 ημέρες.

Variable NameTypeDescription
idIntegerΤο ID της αποστολής.
event_idStringΤο UUID του γεγονότος (CourierHub-Delivery). Ίδιο σε όλες τις προσπάθειες.
event_typeStringshipment.created, shipment.updated, shipment.deleted ή ping.
order_idInteger ή nullΤο εσωτερικό ID της παραγγελίας (null στο ping).
shipment_statusString ή nullΗ κατάσταση της αποστολής τη στιγμή του γεγονότος.
statusStringpending (σε αναμονή ή θα επαναληφθεί), succeeded ή failed.
attemptsIntegerΠόσες προσπάθειες έχουν γίνει.
response_statusInteger ή nullΤο HTTP status της τελευταίας απάντησης.
response_bodyString ή nullΤο body της τελευταίας απάντησης (έως 2048 bytes) ή ο λόγος που δεν στάλθηκε.
payloadObjectΤο ακριβές περιεχόμενο που στάλθηκε, δείτε Webhooks.
delivered_atString ή nullΠότε παραδόθηκε επιτυχώς (ISO 8601, UTC).
created_atStringΠότε δημιουργήθηκε η αποστολή (ISO 8601, UTC).

Παράδειγμα επιτυχημένης αναζήτησης.

json
{
    "data": [
        {
            "id": 1,
            "event_id": "8661d116-e936-4624-b877-3ad18c9e15cf",
            "event_type": "ping",
            "order_id": null,
            "shipment_status": null,
            "status": "succeeded",
            "attempts": 1,
            "response_status": 200,
            "response_body": "OK",
            "payload": {
                "id": "8661d116-e936-4624-b877-3ad18c9e15cf",
                "type": "ping",
                "created_at": "2026-10-15T07:00:00Z",
                "data": {
                    "endpoint_id": 1,
                    "message": "Test event from CourierHub."
                }
            },
            "delivered_at": "2026-10-15T07:00:00Z",
            "created_at": "2026-10-15T07:00:00Z"
        }
    ],
    "links": {
        "next": null,
        "prev": null
    },
    "meta": {
        "per_page": 2,
        "next_cursor": null,
        "prev_cursor": null
    }
}
bash
curl "https://courierhub.gr/api/v2/webhook-endpoints/1/deliveries?per_page=2" \
  -H "Authorization: Bearer chub_YOUR_API_TOKEN"

Released under the MIT License.

Copyright © 2024 CourierHub