Menghubungkan aplikasi Anda ke automation

Kirim event aplikasi saat sesuatu terjadi di sistem Anda, misalnya pesanan dibuat atau pembayaran diterima. Event dapat memulai run, melanjutkan run yang sedang menunggu, atau membatalkan run yang cocok dengan aturan pembatalan. Setiap automation memiliki satu URL event untuk ketiga kegunaan tersebut.

Automations is in Early access. Your workspace permissions determine which actions you can perform.

Jika Anda tidak dapat membuka Automations atau membuat draf, lihat akses workspace dan kontrol pengeditan.

Konfigurasi event yang memulai run

Buat automation dengan Event from your application sebagai trigger-nya.
Atur Event name, misalnya order.created. Nama bersifat case-sensitive dan dapat berisi huruf, angka, titik, garis bawah, atau tanda hubung.
Tentukan Event fields untuk data yang dikirim aplikasi Anda. Untuk pesanan, tambahkan field string bernama order_id. Langkah-langkah selanjutnya dapat menggunakan field ini.
Publikasikan automation. Layar sukses menampilkan How to start a run, termasuk URL event dan contoh request.

Untuk menemukan detail koneksi lagi, pilih trigger lalu klik How to connect your application di quick edit. Editor yang diperluas menampilkan kontrol koneksi.

Simulasikan draf atau jalankan versi yang dipublikasikan

Gunakan Preview workflow dengan data sampel untuk menyimulasikan draf Anda tanpa mengirim pesan atau mengubah data. Menjalankan perintah cURL, mengklik Send event…, atau menggunakan Start run mengeksekusi automation yang dipublikasikan dan dapat melakukan aksi nyata. Perubahan draf yang tersimpan maupun belum tersimpan tidak berlaku untuk run tersebut.

Publikasikan automation sebelum mengirim event. Jika belum ada versi yang dipublikasikan, request langsung ditolak; event tidak diantrikan atau disimpan untuk nanti. Contoh di editor dapat mencerminkan perubahan draf, jadi publikasikan perubahan tersebut sebelum mengirim data yang bergantung padanya.

Salin URL dan kirim event

Gunakan Copy request untuk mendapatkan perintah cURL yang berisi URL, header, dan body contoh. Ganti nilai contoh dengan data dari aplikasi Anda.

URL menyertakan ID workspace dan automation:

Contoh kode

POST https://<your-regional-api-host>/v1/hooks/automations/<workspace-id>/<automation-id>

Gunakan URL lengkap yang disalin dari dashboard. Anda tidak memerlukan header X-Workspace-Id. Opsi autentikasi saat ini adalah No authentication: siapa pun yang memiliki URL ini dapat mengirim event. Simpan URL ini di konfigurasi server Anda.

Untuk automation yang dikonfigurasi untuk order.created, atur AUTOMATION_EVENT_URL ke URL yang disalin dan kirim:

Contoh kode

curl --request POST "$AUTOMATION_EVENT_URL" \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "order.created",
    "data": { "order_id": "order_123" }
  }'

Atur type ke nama event yang dikonfigurasi dan data ke objek yang sesuai dengan event fields. Anda juga dapat menyertakan occurred_at sebagai timestamp RFC 3339; nilai default-nya adalah waktu event diterima.

Respons 202 Accepted dengan status: "queued" mengonfirmasi bahwa event telah diantrikan. Bird menghasilkan identifier event dan mengembalikannya sebagai event_id. Buka tab Runs pada automation untuk memeriksa eksekusi. Penerimaan antrean tidak mengonfirmasi bahwa event cocok dengan trigger atau bahwa run telah dimulai.

Anda juga dapat menggunakan Send event… di dashboard untuk mengirim contoh tanpa terminal. Ini mengirim event nyata.

Melanjutkan run yang menunggu event

Langkah tunggu menggunakan URL automation yang sama dengan trigger. Nama event dan subject_key mengidentifikasi apa yang terjadi dan run mana yang harus menerimanya.

Di Automation settings, aktifkan Skip overlapping runs dan Use a business key. Atur Business key ke nilai yang mengidentifikasi pesanan, faktur, atau objek lainnya. Untuk contoh pesanan, gunakan ekspresi trigger.data.data.order_id.
Tambahkan Wait for application event dan konfigurasi nama event, event fields, dan timeout-nya. Misalnya, tunggu order.paid dengan field string payment_id.
Publikasikan, kirim event awal, dan tunggu hingga run-nya muncul di Runs.
Kirim event lanjutan ke URL yang sama, dengan subject_key sama dengan business key run:

Contoh kode

{
  "type": "order.paid",
  "subject_key": "order_123",
  "data": { "payment_id": "payment_456" }
}

subject_key adalah nilai business key, misalnya order_123; bukan event ID atau run ID. Tampilan koneksi yang diperluas pada langkah tunggu menampilkan panduan untuk key yang Anda konfigurasi.

Event yang cocok dapat ditangkap setelah run dimulai, bahkan sebelum mencapai langkah tunggu. Event yang diproses sebelum run yang cocok ada tidak disimpan untuk run di masa mendatang. Langkah tunggu dengan filter hanya melanjutkan jika event fields dan filter-nya cocok. Run mengambil jalur timeout jika tidak ada event yang memenuhi syarat diproses sebelum batas waktunya.

Aturan pembatalan di Automation settings juga menggunakan URL ini. Aturan dapat menargetkan semua run aktif dari automation, atau run yang cocok dengan subject_key. Konfigurasi filter untuk mempersempit run mana yang dibatalkan. Pembatalan tidak dapat membatalkan aksi yang sudah terjadi.

Versi yang dipublikasikan dan automation yang dijeda

Run baru menggunakan versi yang aktif saat event diproses. Run yang sudah ada mempertahankan versi aslinya, termasuk event fields dan kondisi tunggu. Mempublikasikan format event yang diubah tidak memperbarui run yang sudah dimulai.

Menjeda automation yang dipublikasikan menghentikan run baru. Event masih dapat melanjutkan atau membatalkan run yang ada selama automation dijeda.

Menangani pengiriman dan percobaan ulang

Event diproses secara asinkron dan dapat dicoba ulang atau diproses tidak berurutan. Tunggu hingga run awal ada sebelum mengirim event lanjutan. occurred_at pada event tidak mengontrol urutan pemrosesan, memperpanjang waktu tunggu, atau mencegah timeout.

Perlindungan percobaan ulang bersifat terbatas. Jika catatan percobaan ulang kedaluwarsa atau hilang, event dapat diproses lagi, kemungkinan terhadap versi yang lebih baru atau run aktif yang berbeda. Rancang aplikasi Anda untuk menoleransi event duplikat.

Untuk mengaktifkan perlindungan pengulangan, sertakan Idempotency-Key pada percobaan pertama, lalu gunakan kembali dengan URL yang sama dan body yang tidak berubah untuk percobaan ulang. Gunakan key baru untuk setiap permintaan baru. Pemutaran ulang mengembalikan event_id yang sama. Panduan idempotensi menjelaskan jendela pemutaran ulang yang terbatas dan respons konflik.

Memecahkan masalah event

Request mengembalikan 4xx: Periksa detail error pada respons, URL, serta field type dan objek data yang diperlukan. Kirim Content-Type: application/json. Seluruh body request harus berukuran maksimal 25 KB (25.000 byte); body yang lebih besar mengembalikan 413.
Automation belum dipublikasikan: Publikasikan sebelum mengirim event. Event yang ditolak tidak disimpan; kirim request baru setelah dipublikasikan.
Permintaan mengembalikan 202 tetapi tidak ada run yang dimulai: Periksa apakah automasi aktif, nama event cocok dengan trigger-nya, dan data sesuai dengan event field yang dipublikasikan. Perlindungan tumpang tindih dapat melewatkan run baru selama run lain masih aktif. Periksa juga kuota run bulanan; run yang dilewatkan saat batas tercapai tidak diantrikan untuk bulan berikutnya.
Run tetap di langkah tunggu: Periksa nama event, business key yang tepat, field data, filter, dan timeout. Gunakan format event dari versi terpublikasi asli run tersebut.
Percobaan ulang mengembalikan konflik: Coba lagi dengan key asli dan request yang tidak diubah. Jika Anda ingin mengirim event yang berbeda, gunakan key baru.

Envelope request diperiksa sebelum diantrikan. Data event diperiksa terhadap trigger, langkah tunggu, dan aturan pembatalan selama pemrosesan, sehingga event yang sudah diantrikan bisa saja tidak cocok dengan salah satu dari semuanya.

Langkah selanjutnya

Buka Automations untuk mengonfigurasi dan mempublikasikan workflow Anda.
Tangani percobaan ulang idempoten di aplikasi Anda.
Tunggu event dalam workflow yang sedang berjalan.
Jelajahi panduan Automations.

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Panduan implementasiPreview your first automation