# 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](/docs/guides/automations/troubleshooting#automations-is-missing-from-the-dashboard).

## Konfigurasi event yang memulai run

1. Buat automation dengan **Event from your application** sebagai trigger-nya.
2. Atur **Event name**, misalnya `order.created`. Nama bersifat case-sensitive dan dapat berisi huruf, angka, titik, garis bawah, atau tanda hubung.
3. Tentukan **Event fields** untuk data yang dikirim aplikasi Anda. Untuk pesanan, tambahkan field string bernama `order_id`. Langkah-langkah selanjutnya dapat menggunakan field ini.
4. 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:

```text
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:

```bash
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.

1. 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`.
2. Tambahkan **Wait for application event** dan konfigurasi nama event, event fields, dan timeout-nya. Misalnya, tunggu `order.paid` dengan field string `payment_id`.
3. Publikasikan, kirim event awal, dan tunggu hingga run-nya muncul di **Runs**.
4. Kirim event lanjutan ke URL yang sama, dengan `subject_key` sama dengan business key run:

```json
{
  "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](/docs/guides/idempotency) 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](/docs/guides/automations/runs#early-access-run-allowance); 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**](https://bird.com/dashboard/w/automations) untuk mengonfigurasi dan mempublikasikan workflow Anda.
- [Tangani percobaan ulang idempoten](/docs/guides/idempotency) di aplikasi Anda.
- [Tunggu event](/docs/guides/automations/waits) dalam workflow yang sedang berjalan.
- [Jelajahi panduan Automations](/docs/guides/automations).

## Related resources

- [Preview your first automation](/docs/get-started/automations) (docs)