Webhooks

Το Usher μπορεί να ενημερώνει τους διακομιστές σας για ό,τι συμβαίνει σε ένα περιβάλλον τη στιγμή που συμβαίνει: κάποιος εγγράφεται, συνδέεται, αλλάζει τα στοιχεία του ή φεύγει. Κάθε συμβάν είναι ένα υπογεγραμμένο POST σε μια διεύθυνση που επιλέγετε, και ξαναστέλνεται αν ο διακομιστής σας δεν απαντήσει.

Προσθέστε ένα τελικό σημείο

Στο Usher Console, ανοίξτε το περιβάλλον και, στη συνέχεια, Webhooks → Νέο τελικό σημείο. Δώστε μια δική σας διεύθυνση https:// και επιλέξτε τα συμβάντα για τα οποία πρέπει να ενημερώνεται. Το Console δείχνει το μυστικό υπογραφής του τελικού σημείου (whsec_…) μία φορά: κρατήστε το μαζί με τα άλλα μυστικά του διακομιστή σας.

Το Αποστολή δοκιμής στέλνει ένα συμβάν webhook.test μόνο σε αυτό το τελικό σημείο, ανεξάρτητα από τις συνδρομές του.

Τι φτάνει

POST /usher/webhooks HTTP/1.1
content-type: application/json
user-agent: Usher-Webhooks/1
webhook-id: msg_2fk7x…
webhook-timestamp: 1793643116
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

{
  "type": "user.created",
  "timestamp": "2026-11-02T18:11:56.412Z",
  "data": {
    "user": {
      "id": "Qz3m…",
      "email": "lena@acme.com",
      "emailVerified": false,
      "name": "Lena Live",
      "image": null,
      "banned": false,
      "createdAt": "2026-11-02T18:11:56.380Z",
      "updatedAt": "2026-11-02T18:11:56.380Z"
    }
  }
}

Τα συμβάντα περιγράφουν χρήστες και περιόδους σύνδεσης, ποτέ μυστικά: χωρίς διακριτικά, χωρίς κατακερματισμούς συνθηματικών, χωρίς ρόλους, και όχι τον λόγο για τον οποίο αποκλείστηκε κάποιος.

Ελέγξτε κάθε παράδοση

Το Usher υπογράφει κατά την προδιαγραφή Standard Webhooks, οπότε οποιαδήποτε από τις βιβλιοθήκες της ελέγχει την υπογραφή για εσάς. Απορρίψτε ό,τι δεν επαληθεύεται. Οι βιβλιοθήκες απορρίπτουν επίσης μια χρονοσφραγίδα που απέχει πάνω από πέντε λεπτά, ώστε μια παλιά παράδοση να μην μπορεί να αναπαραχθεί.

// a route that receives Usher's webhooks (Node, the standardwebhooks package)
import { Webhook } from 'standardwebhooks'

const wh = new Webhook(process.env.USHER_WEBHOOK_SECRET!) // whsec_…, from Usher Console

export async function POST(request: Request) {
  const body = await request.text() // the raw body: the signature covers it byte for byte
  let event: { type: string; timestamp: string; data: Record<string, unknown> }
  try {
    event = wh.verify(body, Object.fromEntries(request.headers)) as typeof event
  } catch {
    return new Response('bad signature', { status: 400 })
  }
  // webhook-id is the same on every attempt: skip one you have handled already
  if (await alreadyHandled(request.headers.get('webhook-id')!)) return new Response(null, { status: 204 })
  await queue(event) // answer quickly; do the work afterwards
  return new Response(null, { status: 204 })
}

• Απαντήστε μέσα σε 15 δευτερόλεπτα με οποιοδήποτε 2xx. Οτιδήποτε άλλο, μαζί και μια ανακατεύθυνση, μετρά ως αποτυχία.
• Να περιμένετε επαναλήψεις. Ένα μήνυμα κρατά το webhook-id του σε κάθε προσπάθεια· παραλείψτε όποιο έχετε ήδη χειριστεί.
• Μη βασίζεστε στη σειρά. Οι επαναλήψεις μπορεί να φτάσουν μετά από νεότερα συμβάντα.

Όταν ο διακομιστής σας δεν απαντά

Το Usher προσπαθεί ξανά μετά από 5 δευτερόλεπτα, 5 λεπτά, 30 λεπτά, 2 ώρες, 5 ώρες, 10 ώρες και 10 ώρες (περίπου μιάμιση μέρα συνολικά) και μετά σταματά. Το αρχείο παραδόσεων του Console δείχνει τις προσπάθειες κάθε μηνύματος και την τελευταία απάντηση του διακομιστή σας, και το Αποστολή ξανά ξεκινά μια παράδοση από την αρχή.

Νέο μυστικό

Το Νέο μυστικό στο Console δημιουργεί ένα ακόμη και το δείχνει μία φορά. Για τις επόμενες 24 ώρες κάθε παράδοση φέρει δύο υπογραφές, μία ανά μυστικό, ώστε να μπορείτε να αναπτύξετε το νέο μυστικό χωρίς να χάσετε τίποτα. Μετά από αυτό υπογράφει μόνο το νέο.

Από πού έρχονται οι παραδόσεις

Τα webhooks φεύγουν από το Usher μέσω του διακομιστή μεσολάβησης εξόδου του, που δεν συνδέεται σε ιδιωτικές ή εσωτερικές διευθύνσεις. Ένα τελικό σημείο πρέπει να είναι διεύθυνση https:// σε δημόσιο όνομα: όχι διεύθυνση IP, ιδιωτικό όνομα ή διεύθυνση στους τομείς του ίδιου του Usher.